Skip to content

Commit c21c4fc

Browse files
jeff-phillips-18jeff-phillips-18
committed
Initial Version
0 parents  commit c21c4fc

26 files changed

+6090
-0
lines changed

‎.cursorignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)

‎.gitignore‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Dependencies
2+
node_modules/
3+
npm-debug.log*
4+
yarn-debug.log*
5+
yarn-error.log*
6+
7+
# Build output
8+
dist/
9+
build/
10+
*.tsbuildinfo
11+
12+
# Environment variables
13+
.env
14+
.env.local
15+
.env.development.local
16+
.env.test.local
17+
.env.production.local
18+
19+
# IDE and editor files
20+
.vscode/
21+
.idea/
22+
*.swp
23+
*.swo
24+
*~
25+
26+
# OS generated files
27+
.DS_Store
28+
.DS_Store?
29+
._*
30+
.Spotlight-V100
31+
.Trashes
32+
ehthumbs.db
33+
Thumbs.db
34+
35+
# Logs
36+
logs
37+
*.log
38+
39+
# Runtime data
40+
pids
41+
*.pid
42+
*.seed
43+
*.pid.lock
44+
45+
# Coverage directory used by tools like istanbul
46+
coverage/
47+
*.lcov
48+
49+
# Optional npm cache directory
50+
.npm
51+
52+
# Optional REPL history
53+
.node_repl_history
54+
55+
# Output of 'npm pack'
56+
*.tgz
57+
58+
# Yarn Integrity file
59+
.yarn-integrity

‎.pf-ai-documentation/README.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# PatternFly React Development Rules
2+
3+
> **Starting a new project?**
4+
> For a quick start with PatternFly React, use the [patternfly/patternfly-react-seed](https://github.com/patternfly/patternfly-react-seed) app. It provides a basic build, layout, and scaffolding for new PatternFly applications, including recommended tooling and project structure.
5+
6+
Essential rules and guidelines for AI coders working with PatternFly React applications.
7+
8+
## Quick Navigation
9+
10+
### 🚀 Setup & Environment
11+
- [**Setup Rules**](./setup/README.md) - Project initialization requirements
12+
- [**Quick Start**](./setup/quick-start.md) - Essential setup steps
13+
- [**Environment Rules**](./setup/development-environment.md) - Development configuration
14+
15+
### 📚 Core Rules
16+
- [**PatternFly Guidelines**](./guidelines/README.md) - Core development principles
17+
- [**Component Rules**](./guidelines/component-architecture.md) - Component structure requirements
18+
- [**Styling Rules**](./guidelines/styling-standards.md) - CSS and styling requirements
19+
- [**AI Prompt Guidance**](./guidelines/ai-prompt-guidance.md) - How to write effective AI prompts
20+
- [**Deployment Guide**](./guidelines/deployment-guide.md) - How to deploy prototypes
21+
22+
### 🧩 Component Rules
23+
- [**Layout Rules**](./components/layout/README.md) - Page structure requirements
24+
- [**Table Component Rules**](./components/data-display/table.md) - Table usage and best practices
25+
- [**Data View Component Rules**](./components/data-display/README.md) - Data view usage and best practices
26+
27+
### 📊 Specialized Rules
28+
- [**Charts Rules**](./charts/README.md) - PatternFly Charts requirements
29+
- [**Chatbot Rules**](./chatbot/README.md) - PatternFly Chatbot requirements
30+
31+
### 🔧 Troubleshooting
32+
- [**Common Issues**](./troubleshooting/common-issues.md) - Problem resolution rules
33+
34+
### 📖 Resources
35+
- [**External Links**](./resources/external-links.md) - Official documentation links
36+
37+
## Usage Rules for AI Coders
38+
39+
1. **Always use PatternFly v6** - Use `pf-v6-` prefixed classes only
40+
2. **Component-first approach** - Use PatternFly components before custom solutions
41+
3. **Consult documentation** - Reference [PatternFly.org](https://www.patternfly.org/) for examples
42+
4. **Follow accessibility** - Implement proper ARIA labels and keyboard navigation
43+
5. **Use utility classes** - Prefer PatternFly utilities over custom CSS
44+
6. **Handle states** - Always implement loading, error, and empty states
45+
46+
## ⚠️ Common AI Coding Issues Addressed
47+
48+
Based on feedback, these rules prevent frequent AI-generated errors:
49+
50+
- **❌ No CSS modules syntax** - `className={styles.x}` doesn't work in this project
51+
- **❌ No non-existent components** - Verify components exist before using
52+
- **❌ No inline styles for layout** - Use PatternFly utilities instead
53+
- **✅ Chart imports must include `/victory`** - Critical for chart components
54+
- **✅ Always include accessibility attributes** - Keyboard navigation and ARIA labels
55+
- **✅ Use specific, detailed prompts** - See [AI Prompt Guidance](./guidelines/ai-prompt-guidance.md)
56+
57+
## Documentation Structure
58+
59+
Each file contains:
60+
- **Rules** - Specific requirements to follow
61+
- **Do's and Don'ts** - Clear guidance on what to avoid
62+
- **Links** - References to official PatternFly documentation
63+
- **Quick examples** - Minimal code patterns when needed
64+
65+
## Reference Documentation
66+
67+
- [PatternFly.org](https://www.patternfly.org/)
68+
- [PatternFly React GitHub Repository](https://github.com/patternfly/patternfly-react)
69+
70+
> For all rules and examples, consult both PatternFly.org and the official GitHub repository. When using AI tools, leverage context7 to fetch the latest docs from these sources.

‎.pf-ai-documentation/charts/README.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
# Charts Rules
2+
3+
Essential rules for PatternFly Charts implementation using Victory.js and ECharts.
4+
5+
## Related Files
6+
- [**Component Architecture**](../guidelines/component-architecture.md) - Chart component structure rules
7+
- [**Performance Optimization**](../troubleshooting/performance.md) - Chart performance considerations
8+
9+
## Installation Rules
10+
11+
### Required Installation
12+
```bash
13+
# ✅ Victory-based charts (recommended)
14+
npm install @patternfly/react-charts victory
15+
16+
# ✅ ECharts-based charts (alternative)
17+
npm install @patternfly/react-charts echarts
18+
19+
# ✅ Patternfly for charts css variables (recommended)
20+
npm install @patternfly/patternfly
21+
```
22+
23+
### Import Rules
24+
- ✅ **CRITICAL: Use specific import paths** - Import from `/victory` or `/echarts` subdirectories
25+
- ❌ **Don't use general imports** - Avoid importing from main package
26+
- ⚠️ **Common Error**: AI assistants often forget the `/victory` path
27+
28+
```jsx
29+
// ✅ Correct imports - MUST include /victory
30+
import { ChartDonut, ChartLine, ChartBar } from '@patternfly/react-charts/victory';
31+
import { EChart } from '@patternfly/react-charts/echarts';
32+
33+
// ❌ Wrong imports - Missing /victory will cause "Module not found" errors
34+
import { ChartDonut } from '@patternfly/react-charts';
35+
```
36+
37+
### Import PatternFly Charts CSS
38+
```jsx
39+
// In your main App.js or index.js
40+
import '@patternfly/patternfly/patternfly-charts.css';
41+
```
42+
43+
### Critical Import Path Troubleshooting
44+
45+
**⚠️ MOST COMMON ISSUE**: Chart components cannot be found
46+
47+
```bash
48+
# Error message you'll see:
49+
Module not found: Can't resolve '@patternfly/react-charts'
50+
```
51+
52+
**Solutions in order:**
53+
1. **Fix import paths** - Add `/victory` to your imports:
54+
```jsx
55+
// Change this:
56+
import { ChartDonut } from '@patternfly/react-charts';
57+
58+
// To this:
59+
import { ChartDonut } from '@patternfly/react-charts/victory';
60+
```
61+
62+
2. **Install Victory dependency**:
63+
```bash
64+
npm install victory
65+
```
66+
67+
3. **Clear cache and reinstall**:
68+
```bash
69+
rm -rf node_modules package-lock.json
70+
npm install
71+
```
72+
73+
4. **Verify installation**:
74+
```bash
75+
# Check if both packages are installed
76+
npm list @patternfly/react-charts
77+
npm list victory
78+
```
79+
80+
## Chart Implementation Rules
81+
82+
### Color Rules
83+
- ✅ **Use PatternFly chart color tokens** - For consistency with design system
84+
- ❌ **Don't use hardcoded colors** - Use design tokens instead
85+
86+
```jsx
87+
// ✅ Correct - Use PatternFly color tokens
88+
const chartColors = [
89+
'var(--pf-t--chart--color--blue--300)',
90+
'var(--pf-t--chart--color--green--300)',
91+
'var(--pf-t--chart--color--orange--300)'
92+
];
93+
94+
<ChartDonut data={data} colorScale={chartColors} />
95+
```
96+
97+
### Responsive Rules
98+
- ✅ **Implement responsive sizing** - Charts must work on all screen sizes
99+
- ✅ **Use container-based dimensions** - Not fixed width/height
100+
- ❌ **Don't hardcode dimensions** - Charts must be responsive
101+
102+
```jsx
103+
// ✅ Required responsive pattern
104+
const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
105+
106+
useEffect(() => {
107+
const updateDimensions = () => {
108+
if (containerRef.current) {
109+
const { width, height } = containerRef.current.getBoundingClientRect();
110+
setDimensions({ width, height });
111+
}
112+
};
113+
updateDimensions();
114+
window.addEventListener('resize', updateDimensions);
115+
return () => window.removeEventListener('resize', updateDimensions);
116+
}, []);
117+
```
118+
119+
### Accessibility Rules
120+
- ✅ **Provide ARIA labels** - For screen reader support
121+
- ✅ **Use high contrast colors** - Meet WCAG standards
122+
- ✅ **Support keyboard navigation** - Add tabIndex and role
123+
124+
```jsx
125+
// ✅ Required accessibility pattern
126+
<ChartDonut
127+
data={data}
128+
ariaDesc="Chart showing user distribution"
129+
ariaTitle="User Status Chart"
130+
tabIndex={0}
131+
role="img"
132+
/>
133+
```
134+
135+
### State Management Rules
136+
- ✅ **Handle loading states** - Show spinners during data loading
137+
- ✅ **Handle error states** - Show error messages with retry
138+
- ✅ **Handle empty states** - Show appropriate empty messages
139+
- ✅ **Use data memoization** - For performance optimization
140+
141+
```jsx
142+
// ✅ Required state handling
143+
if (isLoading) return <Spinner />;
144+
if (error) return <EmptyState><EmptyStateHeader titleText="Chart error" /></EmptyState>;
145+
if (!data?.length) return <EmptyState><EmptyStateHeader titleText="No data" /></EmptyState>;
146+
147+
const processedData = useMemo(() => {
148+
return rawData.map(item => ({ x: item.date, y: item.value }));
149+
}, [rawData]);
150+
```
151+
152+
### Integration Rules
153+
- ✅ **Use with PatternFly components** - Integrate charts in Cards, PageSections
154+
- ✅ **Follow grid layouts** - Use PatternFly grid for chart dashboards
155+
- ❌ **Don't create standalone chart pages** - Integrate with PatternFly layout
156+
157+
```jsx
158+
// ✅ Required integration pattern
159+
import { Card, CardTitle, CardBody } from '@patternfly/react-core';
160+
161+
<Card>
162+
<CardTitle>Chart Title</CardTitle>
163+
<CardBody>
164+
<ChartDonut data={data} />
165+
</CardBody>
166+
</Card>
167+
```
168+
169+
## Performance Rules
170+
171+
### Required Optimizations
172+
- ✅ **Use lazy loading for heavy charts** - Improve initial page load
173+
- ✅ **Memoize data processing** - Use useMemo for expensive calculations
174+
- ✅ **Implement proper loading states** - Show feedback during data loading
175+
176+
```jsx
177+
// ✅ Required performance patterns
178+
const LazyChart = lazy(() => import('./HeavyChart'));
179+
180+
<Suspense fallback={<Spinner />}>
181+
<LazyChart />
182+
</Suspense>
183+
```
184+
185+
## Essential Do's and Don'ts
186+
187+
### ✅ Do's
188+
- Use PatternFly chart color tokens for consistency
189+
- Implement responsive sizing for different screen sizes
190+
- Provide proper ARIA labels and descriptions
191+
- Handle loading, error, and empty states
192+
- Use appropriate chart types for your data
193+
- Optimize performance with data memoization
194+
- Integrate charts with PatternFly layout components
195+
196+
### ❌ Don'ts
197+
- Hardcode chart dimensions without responsive design
198+
- Use colors that don't meet accessibility standards
199+
- Skip loading states for charts with async data
200+
- Ignore keyboard navigation and screen reader support
201+
- Create overly complex charts
202+
- Mix different charting libraries inconsistently
203+
- Forget to handle empty data states
204+
205+
## Common Issues
206+
207+
### Module Not Found
208+
- **Clear cache**: `rm -rf node_modules package-lock.json`
209+
- **Reinstall**: `npm install`
210+
- **Check paths**: Verify import paths are correct
211+
212+
### Chart Not Rendering
213+
- **Check container dimensions**: Ensure parent has width/height
214+
- **Verify data format**: Data must match chart expectations
215+
- **Check console**: Look for Victory.js or ECharts warnings
216+
217+
### Performance Issues
218+
- **Use data memoization**: useMemo for expensive calculations
219+
- **Implement lazy loading**: For heavy chart components
220+
- **Optimize re-renders**: Use React.memo for chart components
221+
222+
#### Issue: Chart colors not correct
223+
```bash
224+
# Symptoms: Chart color variables (--pf-v6-chart-color-blue-100, --pf-t--chart--color--blue--300) are not defined
225+
```
226+
227+
**Solutions**:
228+
1. **Install patternfly package**:
229+
```bash
230+
npm install @patternfly/patternfly
231+
```
232+
233+
2. **Import PatternFly Charts CSS**:
234+
```jsx
235+
// In your main App.js or index.js
236+
import '@patternfly/patternfly/patternfly-charts.css';
237+
```
238+
239+
## Quick Reference
240+
- **[PatternFly Charts README](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts#readme)** - Installation and usage
241+
- **[Victory.js Documentation](https://formidable.com/open-source/victory/)** - Chart library documentation
242+
- **[PatternFly Chart Guidelines](https://www.patternfly.org/charts/about)** - Design guidelines
243+
244+
## Reference Documentation
245+
246+
- [PatternFly Charts on PatternFly.org](https://www.patternfly.org/charts/about)
247+
- [PatternFly React Charts GitHub Repository](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts)
248+
249+
> For the most up-to-date documentation and code examples, consult both PatternFly.org and the official GitHub repository. When using AI tools, leverage context7 to fetch the latest docs from these sources.

0 commit comments

Comments
 (0)