From 26ae7b6025682eb5a54e7351fb052f80558db905 Mon Sep 17 00:00:00 2001 From: CD Cabrera Date: Mon, 9 Mar 2026 11:41:20 -0400 Subject: [PATCH] refactor(docs): migrate to ai-helpers --- docs/development.md | 36 +- documentation/README.md | 70 -- documentation/charts/README.md | 276 ------ documentation/chatbot/README.md | 196 ----- documentation/component-groups/README.md | 99 --- documentation/components/README.md | 11 - .../components/data-display/README.md | 222 ----- .../components/data-display/table.md | 190 ---- documentation/components/layout/README.md | 167 ---- documentation/core/README.md | 67 -- documentation/guidelines/README.md | 86 -- .../guidelines/ai-prompt-guidance.md | 146 ---- .../guidelines/component-architecture.md | 92 -- documentation/guidelines/deployment-guide.md | 242 ------ documentation/guidelines/styling-standards.md | 419 --------- documentation/resources/README.md | 37 - documentation/resources/external-links.md | 229 ----- documentation/resources/local-files.md | 30 - documentation/setup/README.md | 81 -- .../setup/development-environment.md | 236 ----- documentation/setup/quick-start.md | 129 --- documentation/troubleshooting/README.md | 57 -- .../troubleshooting/common-issues.md | 811 ------------------ package.json | 1 - .../options.defaults.test.ts.snap | 2 +- .../server.getResources.test.ts.snap | 2 +- .../tool.patternFlyDocs.test.ts.snap | 2 +- .../tool.searchPatternFlyDocs.test.ts.snap | 4 +- src/__tests__/docs.json.test.ts | 50 +- src/__tests__/server.getResources.test.ts | 7 +- src/docs.json | 158 +++- src/options.defaults.ts | 10 +- src/server.getResources.ts | 15 +- .../__snapshots__/httpTransport.test.ts.snap | 34 - .../__snapshots__/stdioTransport.test.ts.snap | 34 - tests/e2e/httpTransport.test.ts | 12 +- tests/e2e/stdioTransport.test.ts | 11 +- tests/e2e/utils/fetchMock.ts | 2 + 38 files changed, 223 insertions(+), 4050 deletions(-) delete mode 100644 documentation/README.md delete mode 100644 documentation/charts/README.md delete mode 100644 documentation/chatbot/README.md delete mode 100644 documentation/component-groups/README.md delete mode 100644 documentation/components/README.md delete mode 100644 documentation/components/data-display/README.md delete mode 100644 documentation/components/data-display/table.md delete mode 100644 documentation/components/layout/README.md delete mode 100644 documentation/core/README.md delete mode 100644 documentation/guidelines/README.md delete mode 100644 documentation/guidelines/ai-prompt-guidance.md delete mode 100644 documentation/guidelines/component-architecture.md delete mode 100644 documentation/guidelines/deployment-guide.md delete mode 100644 documentation/guidelines/styling-standards.md delete mode 100644 documentation/resources/README.md delete mode 100644 documentation/resources/external-links.md delete mode 100644 documentation/resources/local-files.md delete mode 100644 documentation/setup/README.md delete mode 100644 documentation/setup/development-environment.md delete mode 100644 documentation/setup/quick-start.md delete mode 100644 documentation/troubleshooting/README.md delete mode 100644 documentation/troubleshooting/common-issues.md diff --git a/docs/development.md b/docs/development.md index f76772be..ddaadb0f 100644 --- a/docs/development.md +++ b/docs/development.md @@ -79,7 +79,7 @@ npx @modelcontextprotocol/inspector-cli \ --cli \ --method tools/call \ --tool-name usePatternFlyDocs \ - --tool-arg urlList='["documentation/guidelines/README.md"]' + --tool-arg name="Button" ``` ## Programmatic usage @@ -88,21 +88,21 @@ npx @modelcontextprotocol/inspector-cli \ The `start()` function accepts an optional `PfMcpOptions` object for programmatic configuration. Use these options to customize behavior, transport, and logging for embedded instances. -| Option | Type | Description | Default | -|:---------------------------|:-----------------------------------------|:----------------------------------------------------------------------|:-------------------| -| `toolModules` | `ToolModule \| ToolModule[]` | Array of tool modules or paths to external tool plugins to be loaded. | `[]` | -| `isHttp` | `boolean` | Enable HTTP transport mode. | `false` | -| `http.port` | `number` | Port for HTTP transport. | `8080` | -| `http.host` | `string` | Host to bind to. | `127.0.0.1` | -| `http.allowedOrigins` | `string[]` | List of allowed CORS origins. | `[]` | -| `http.allowedHosts` | `string[]` | List of allowed host headers. | `[]` | -| `pluginIsolation` | `'none' \| 'strict'` | Isolation preset for external tools-as-plugins. | `'strict'` | -| `logging.level` | `'debug' \| 'info' \| 'warn' \| 'error'` | Set the logging level. | `'info'` | -| `logging.stderr` | `boolean` | Enable terminal logging to stderr. | `false` | -| `logging.protocol` | `boolean` | Forward logs to MCP clients. | `false` | -| `mode` | `'cli' \| 'programmatic' \| 'test'` | Specifies the operation mode. | `'programmatic'` | -| `modeOptions.test.baseUrl` | `string` | Base URL for fixture/mock servers in `test` mode. | `undefined` | -| `docsPath` | `string` | Path to the documentation directory. | (Internal default) | +| Option | Type | Description | Default | +|:---------------------------|:-----------------------------------------|:---------------------------------------------------------------------------------------------------------------------------|:-----------------| +| `toolModules` | `ToolModule \| ToolModule[]` | Array of tool modules or paths to external tool plugins to be loaded. | `[]` | +| `isHttp` | `boolean` | Enable HTTP transport mode. | `false` | +| `http.port` | `number` | Port for HTTP transport. | `8080` | +| `http.host` | `string` | Host to bind to. | `127.0.0.1` | +| `http.allowedOrigins` | `string[]` | List of allowed CORS origins. | `[]` | +| `http.allowedHosts` | `string[]` | List of allowed host headers. | `[]` | +| `pluginIsolation` | `'none' \| 'strict'` | Isolation preset for external tools-as-plugins. | `'strict'` | +| `logging.level` | `'debug' \| 'info' \| 'warn' \| 'error'` | Set the logging level. | `'info'` | +| `logging.stderr` | `boolean` | Enable terminal logging to stderr. | `false` | +| `logging.protocol` | `boolean` | Forward logs to MCP clients. | `false` | +| `mode` | `'cli' \| 'programmatic' \| 'test'` | Specifies the operation mode. | `'programmatic'` | +| `modeOptions.test.baseUrl` | `string` | Base URL for fixture/mock servers in `test` mode. | `undefined` | +| `docsPaths` | `string[]` | Whitelist of local documentation directories resolved by `documentation:` slug. When empty (default), the slug is dormant. | `[]` | #### Example usage @@ -124,6 +124,10 @@ const options: PfMcpOptions = { const server: PfMcpInstance = await start(options); ``` +#### About pinned documentation sources + +The documentation catalog `src/docs.json` pins remote resources to specific commit SHAs (or explicit refs) for stability and reproducibility. This avoids unexpected upstream changes from breaking results. The `searchPatternFlyDocs` tool handles these lookups transparently for the user. + **Example: Programmatic test mode** ```typescript import { start, type PfMcpInstance } from '@patternfly/patternfly-mcp'; diff --git a/documentation/README.md b/documentation/README.md deleted file mode 100644 index 905f4013..00000000 --- a/documentation/README.md +++ /dev/null @@ -1,70 +0,0 @@ -# PatternFly React Development Rules - -> **Starting a new project?** -> 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. - -Essential rules and guidelines for AI coders working with PatternFly React applications. - -## Quick Navigation - -### 🚀 Setup & Environment -- [**Setup Rules**](./setup/README.md) - Project initialization requirements -- [**Quick Start**](./setup/quick-start.md) - Essential setup steps -- [**Environment Rules**](./setup/development-environment.md) - Development configuration - -### 📚 Core Rules -- [**PatternFly Guidelines**](./guidelines/README.md) - Core development principles -- [**Component Rules**](./guidelines/component-architecture.md) - Component structure requirements -- [**Styling Rules**](./guidelines/styling-standards.md) - CSS and styling requirements -- [**AI Prompt Guidance**](./guidelines/ai-prompt-guidance.md) - How to write effective AI prompts -- [**Deployment Guide**](./guidelines/deployment-guide.md) - How to deploy prototypes - -### 🧩 Component Rules -- [**Layout Rules**](./components/layout/README.md) - Page structure requirements -- [**Table Component Rules**](./components/data-display/table.md) - Table usage and best practices -- [**Data View Component Rules**](./components/data-display/README.md) - Data view usage and best practices - -### 📊 Specialized Rules -- [**Charts Rules**](./charts/README.md) - PatternFly Charts requirements -- [**Chatbot Rules**](./chatbot/README.md) - PatternFly Chatbot requirements - -### 🔧 Troubleshooting -- [**Common Issues**](./troubleshooting/common-issues.md) - Problem resolution rules - -### 📖 Resources -- [**External Links**](./resources/external-links.md) - Official documentation links - -## Usage Rules for AI Coders - -1. **Always use PatternFly v6** - Use `pf-v6-` prefixed classes only -2. **Component-first approach** - Use PatternFly components before custom solutions -3. **Consult documentation** - Reference [PatternFly.org](https://www.patternfly.org/) for examples -4. **Follow accessibility** - Implement proper ARIA labels and keyboard navigation -5. **Use utility classes** - Prefer PatternFly utilities over custom CSS -6. **Handle states** - Always implement loading, error, and empty states - -## ⚠️ Common AI Coding Issues Addressed - -Based on feedback, these rules prevent frequent AI-generated errors: - -- **❌ No CSS modules syntax** - `className={styles.x}` doesn't work in this project -- **❌ No non-existent components** - Verify components exist before using -- **❌ No inline styles for layout** - Use PatternFly utilities instead -- **✅ Chart imports must include `/victory`** - Critical for chart components -- **✅ Always include accessibility attributes** - Keyboard navigation and ARIA labels -- **✅ Use specific, detailed prompts** - See [AI Prompt Guidance](./guidelines/ai-prompt-guidance.md) - -## Documentation Structure - -Each file contains: -- **Rules** - Specific requirements to follow -- **Do's and Don'ts** - Clear guidance on what to avoid -- **Links** - References to official PatternFly documentation -- **Quick examples** - Minimal code patterns when needed - -## Reference Documentation - -- [PatternFly.org](https://www.patternfly.org/) -- [PatternFly React GitHub Repository](https://github.com/patternfly/patternfly-react) - -> 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. \ No newline at end of file diff --git a/documentation/charts/README.md b/documentation/charts/README.md deleted file mode 100644 index b9c46c29..00000000 --- a/documentation/charts/README.md +++ /dev/null @@ -1,276 +0,0 @@ -# Charts Rules - -Essential rules for PatternFly Charts implementation using Victory.js and ECharts. - -## Installation Rules - -### Required Installation -```bash -# ✅ Victory-based charts (recommended) -npm install @patternfly/react-charts victory - -# ✅ ECharts-based charts (alternative) -npm install @patternfly/react-charts echarts - -# ✅ Patternfly for charts css variables (recommended) -npm install @patternfly/patternfly -``` - -### Import Rules -- ✅ **CRITICAL: Use specific import paths** - Import from `/victory` or `/echarts` subdirectories -- ❌ **Don't use general imports** - Avoid importing from main package -- ⚠️ **Common Error**: AI assistants often forget the `/victory` path - -```jsx -// ✅ Correct imports - MUST include /victory -import { ChartDonut, ChartLine, ChartBar } from '@patternfly/react-charts/victory'; -import { EChart } from '@patternfly/react-charts/echarts'; - -// ❌ Wrong imports - Missing /victory will cause "Module not found" errors -import { ChartDonut } from '@patternfly/react-charts'; -``` - -### Import PatternFly Charts CSS - ```jsx - // In your main App.js or index.js - import '@patternfly/patternfly/patternfly-charts.css'; - ``` - -### Critical Import Path Troubleshooting - -**⚠️ MOST COMMON ISSUE**: Chart components cannot be found - -```bash -# Error message you'll see: -Module not found: Can't resolve '@patternfly/react-charts' -``` - -**Solutions in order:** -1. **Fix import paths** - Add `/victory` to your imports: - ```jsx - // Change this: - import { ChartDonut } from '@patternfly/react-charts'; - - // To this: - import { ChartDonut } from '@patternfly/react-charts/victory'; - ``` - -2. **Install Victory dependency**: - ```bash - npm install victory - ``` - -3. **Clear cache and reinstall**: - ```bash - rm -rf node_modules package-lock.json - npm install - ``` - -4. **Verify installation**: - ```bash - # Check if both packages are installed - npm list @patternfly/react-charts - npm list victory - ``` - -## Chart Implementation Rules - -### Best Practices - -### Color families -- Chart color families include - - red-orange - - orange - - yellow - - teal - - green - - blue - - purple - - black -- Use the same brightness of colors first, then use other brightness - - Base: 300 - - Lightest: 100 - - Darkest: 500 - - Second-lightest: 200 - - Second-darkest: 400 - - Use PatternFly tokens to define your color variables - - --pf-t-chart-color-[color-family]-[brightness] - - example: --pf-t-chart-color-blue-300 -- When selecting colors for your chart, adhere to these general rules: - - Within a color family, use the base color first. Then use the other lighter and darker hues. - - Some families have predetermined uses: - - Blue: Use to show success. - - Red-orange: Use to show failure. Do not use this family unless you're communicating failure. - - Other colors: Use for neutral purposes or categories. - -### Color Rules -- ✅ **Use PatternFly chart color tokens** - For consistency with design system -- ❌ **Don't use hardcoded colors** - Use design tokens instead - -```jsx -// ✅ Correct - Use PatternFly color tokens -const chartBlueColor = [ - 'var(--pf-t--chart--color--[color family 1]--300)', - 'var(--pf-t--chart--color--[color family 2]--300)', - 'var(--pf-t--chart--color--[color family 3]--300)' -]; - - -``` - -### Responsive Rules -- ✅ **Implement responsive sizing** - Charts must work on all screen sizes -- ✅ **Use container-based dimensions** - Not fixed width/height -- ❌ **Don't hardcode dimensions** - Charts must be responsive - -```jsx -// ✅ Required responsive pattern -const [dimensions, setDimensions] = useState({ width: 0, height: 0 }); - -useEffect(() => { - const updateDimensions = () => { - if (containerRef.current) { - const { width, height } = containerRef.current.getBoundingClientRect(); - setDimensions({ width, height }); - } - }; - updateDimensions(); - window.addEventListener('resize', updateDimensions); - return () => window.removeEventListener('resize', updateDimensions); -}, []); -``` - -### Accessibility Rules -- ✅ **Provide ARIA labels** - For screen reader support -- ✅ **Use high contrast colors** - Meet WCAG standards -- ✅ **Support keyboard navigation** - Add tabIndex and role - -```jsx -// ✅ Required accessibility pattern - -``` - -### State Management Rules -- ✅ **Handle loading states** - Show spinners during data loading -- ✅ **Handle error states** - Show error messages with retry -- ✅ **Handle empty states** - Show appropriate empty messages -- ✅ **Use data memoization** - For performance optimization - -```jsx -// ✅ Required state handling -if (isLoading) return ; -if (error) return ; -if (!data?.length) return ; - -const processedData = useMemo(() => { - return rawData.map(item => ({ x: item.date, y: item.value })); -}, [rawData]); -``` - -### Integration Rules -- ✅ **Use with PatternFly components** - Integrate charts in Cards, PageSections -- ✅ **Follow grid layouts** - Use PatternFly grid for chart dashboards -- ❌ **Don't create standalone chart pages** - Integrate with PatternFly layout - -```jsx -// ✅ Required integration pattern -import { Card, CardTitle, CardBody } from '@patternfly/react-core'; - - - Chart Title - - - - -``` - -## Performance Rules - -### Required Optimizations -- ✅ **Use lazy loading for heavy charts** - Improve initial page load -- ✅ **Memoize data processing** - Use useMemo for expensive calculations -- ✅ **Implement proper loading states** - Show feedback during data loading - -```jsx -// ✅ Required performance patterns -const LazyChart = lazy(() => import('./HeavyChart')); - -}> - - -``` - -## Essential Do's and Don'ts - -### ✅ Do's -- Use PatternFly chart color tokens for consistency -- Implement responsive sizing for different screen sizes -- Provide proper ARIA labels and descriptions -- Handle loading, error, and empty states -- Use appropriate chart types for your data -- Optimize performance with data memoization -- Integrate charts with PatternFly layout components - -### ❌ Don'ts -- Hardcode chart dimensions without responsive design -- Use colors that don't meet accessibility standards -- Skip loading states for charts with async data -- Ignore keyboard navigation and screen reader support -- Create overly complex charts -- Mix different charting libraries inconsistently -- Forget to handle empty data states - -## Common Issues - -### Module Not Found -- **Clear cache**: `rm -rf node_modules package-lock.json` -- **Reinstall**: `npm install` -- **Check paths**: Verify import paths are correct - -### Chart Not Rendering -- **Check container dimensions**: Ensure parent has width/height -- **Verify data format**: Data must match chart expectations -- **Check console**: Look for Victory.js or ECharts warnings - -### Performance Issues -- **Use data memoization**: useMemo for expensive calculations -- **Implement lazy loading**: For heavy chart components -- **Optimize re-renders**: Use React.memo for chart components - -#### Issue: Chart colors not correct -```bash -# Symptoms: Chart color variables (--pf-v6-chart-color-blue-100, --pf-t--chart--color--blue--300) are not defined -``` - -**Solutions**: -1. **Install patternfly package**: - ```bash - npm install @patternfly/patternfly - ``` - -2. **Import PatternFly Charts CSS**: - ```jsx - // In your main App.js or index.js - import '@patternfly/patternfly/patternfly-charts.css'; - ``` - -## Quick Reference -- **[PatternFly Charts README](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts#readme)** - Installation and usage -- **[Victory.js Documentation](https://formidable.com/open-source/victory/)** - Chart library documentation -- **[PatternFly Chart Guidelines](https://www.patternfly.org/charts/about-charts)** - Design guidelines -- **[PatternFly Chart Colors](https://www.patternfly.org/charts/colors-for-charts)** - Colors for charts - - - -## Reference Documentation - -- [PatternFly Charts on PatternFly.org](https://www.patternfly.org/charts/about) -- [PatternFly React Charts GitHub Repository](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts) - -> 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. \ No newline at end of file diff --git a/documentation/chatbot/README.md b/documentation/chatbot/README.md deleted file mode 100644 index 3f2ca7bf..00000000 --- a/documentation/chatbot/README.md +++ /dev/null @@ -1,196 +0,0 @@ -# Chatbot Rules - -Essential rules for PatternFly Chatbot implementation and integration patterns. - -## Related Files - -- [**Component Architecture**](../guidelines/component-architecture.md) - Chatbot component structure rules -- [**Styling Standards**](../guidelines/styling-standards.md) - CSS and styling best practices - -## Installation Rules - -### Required Installation - -```bash -# ✅ Install PatternFly Chatbot package -npm install @patternfly/chatbot -``` - -### Required CSS Import - -```jsx -// ✅ MUST import CSS - chatbot components require specific styling -import '@patternfly/chatbot/dist/css/main.css'; -``` - -### Webpack Configuration (if needed) - -```javascript -// stylePaths.js - Add to webpack if CSS not loading -module.exports = [ - require.resolve('@patternfly/chatbot/dist/css/main.css') -]; -``` - -## Import Rules - -### Required Import Pattern - -- ✅ **Use dynamic imports** - Import from `/dist/dynamic/` paths -- ❌ **Don't use standard imports** - May not work with current package structure - -```jsx -// ✅ Correct - Use dynamic imports -import { Chatbot } from '@patternfly/chatbot/dist/dynamic/Chatbot'; -import { ChatbotContent } from '@patternfly/chatbot/dist/dynamic/ChatbotContent'; -import { MessageBox } from '@patternfly/chatbot/dist/dynamic/MessageBox'; -import { Message } from '@patternfly/chatbot/dist/dynamic/Message'; - -// ❌ Wrong - Standard imports may not work -import { Chatbot, ChatbotContent } from '@patternfly/chatbot'; -``` - -## Implementation Rules - -### Required Component Structure - -- ✅ **Use standard chatbot hierarchy** - Chatbot > ChatbotContent > MessageBox + ChatbotFooter -- ✅ **Reference official demos** - Use PatternFly demo source code as templates -- ❌ **Don't create custom chat UI** - Use PatternFly chatbot components - -```jsx -// ✅ Required chatbot structure - - - - - {messages.map(message => ( - - ))} - - - - - - -``` - -### Message State Rules - -- ✅ **Use proper message roles** - 'user', 'assistant', 'system' -- ✅ **Include timestamps** - For message ordering and display -- ✅ **Handle loading states** - Show indicators during API calls -- ✅ **Handle error states** - Show error messages with retry options - -```jsx -// ✅ Required message structure -const createMessage = (content, role) => ({ - id: generateId(), - content, - role, // 'user' | 'assistant' | 'system' - timestamp: new Date(), - status: 'sent' -}); -``` - -### Demo Implementation Rules - -- ✅ **Study official demos** - [Basic](https://www.patternfly.org/patternfly-ai/chatbot/overview/demo/basic-chatbot) and [Embedded](https://www.patternfly.org/patternfly-ai/chatbot/overview/demo/embedded-chatbot) -- ✅ **Use demo source code** - Copy patterns from "View Code" sections -- ✅ **Follow demo structure** - Don't deviate from proven patterns - -### Integration Rules - -- ✅ **Use with PatternFly layout** - Integrate in PageSection, Modal, or Card -- ✅ **Handle responsive design** - Chatbot must work on all screen sizes -- ❌ **Don't create standalone chatbot pages** - Integrate with app layout - -```jsx -// ✅ Required integration pattern - -
- - {/* Chatbot content */} - -
- -``` - -## Accessibility Rules - -### Required Accessibility - -- ✅ **Use proper ARIA labels** - For screen reader support -- ✅ **Implement keyboard navigation** - Full keyboard accessibility -- ✅ **Use semantic roles** - role="application", role="log" -- ✅ **Auto-scroll to new messages** - For better UX - -```jsx -// ✅ Required accessibility pattern - - - {messages.map(message => ( - - ))} - - -``` - -## Essential Do's and Don'ts - -### ✅ Do's - -- Import CSS from `@patternfly/chatbot/dist/css/main.css` -- Use dynamic imports for chatbot components -- Reference official PatternFly demo pages for implementation -- Provide proper ARIA labels and roles for accessibility -- Handle loading states during message processing -- Implement proper error handling for API failures -- Use semantic message roles (user, assistant, system) - -### ❌ Don'ts - -- Skip CSS imports - chatbot components require specific styling -- Ignore demo source code from PatternFly documentation -- Create custom chat UI when PatternFly components exist -- Skip accessibility considerations for screen readers -- Hardcode chatbot dimensions without responsive design -- Mix different chatbot libraries with PatternFly Chatbot - -## Common Issues - -### Styling Issues - -- **Missing styles**: Ensure CSS is imported in main app file -- **Webpack config**: Add CSS path to stylePaths.js if needed - -### Component Issues - -- **Import errors**: Use dynamic import paths `/dist/dynamic/` -- **Component not found**: Verify package is installed and paths are correct - -### Performance Issues - -- **Long conversations**: Implement message virtualization -- **Memory leaks**: Clean up event listeners and subscriptions - -## Quick Reference - -- **[Chatbot Overview](https://www.patternfly.org/patternfly-ai/chatbot/overview)** - Main documentation -- **[Basic Demo](https://www.patternfly.org/patternfly-ai/chatbot/overview/demo/basic-chatbot)** - Simple implementation -- **[Embedded Demo](https://www.patternfly.org/patternfly-ai/chatbot/overview/demo/embedded-chatbot)** - Embedded pattern -- **[Local Documentation](../resources/local-files.md#patternfly-chatbot-txt)** - Project-specific context - -**Note**: This chatbot guidance takes precedence over general PatternFly patterns. Always consult the latest PatternFly Chatbot documentation and demo source code. - -## Reference Documentation - -- [PatternFly Chatbot on PatternFly.org](https://www.patternfly.org/patternfly-ai/chatbot/overview) -- [PatternFly Chatbot GitHub Repository](https://github.com/patternfly/chatbot) - -> 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. - -### Further Reading -- **[PatternFly Chatbot Docs](https://www.patternfly.org/chatbot/overview/)** -- **[Component API](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/components/ChipGroup)** - ChipGroup component API for tags -- **[Accessibility Guide](https://www.patternfly.org/get-started/accessibility-guide)** \ No newline at end of file diff --git a/documentation/component-groups/README.md b/documentation/component-groups/README.md deleted file mode 100644 index dfd96421..00000000 --- a/documentation/component-groups/README.md +++ /dev/null @@ -1,99 +0,0 @@ -# PatternFly Component Groups Rules - -Essential rules for using and contributing to PatternFly React Component Groups. - -## Overview -PatternFly Component Groups are opinionated React components that combine and extend PatternFly base components to provide standardized, reusable solutions for common product needs. They are maintained collaboratively by the PatternFly and Red Hat Hybrid Cloud Console teams, with a focus on accessibility, design consistency, and extensibility. - -- [Component Groups NPM](https://www.npmjs.com/package/@patternfly/react-component-groups) -- [Component Groups GitHub](https://github.com/patternfly/react-component-groups) -- [Migration Guide](https://github.com/patternfly/react-component-groups/blob/main/migration.md) - -## Installation Rules - -### Required Installation -```bash -npm install @patternfly/react-component-groups -``` - -### Required CSS Import -```jsx -import '@patternfly/react-component-groups/dist/css/main.css'; -``` - -## Import Rules - -### Required Import Pattern -- ✅ **Use dynamic imports** from `/dist/dynamic/` paths -- ❌ **Don't use standard imports** - -```jsx -// ✅ Correct -import { BulkSelect } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect'; - -// ❌ Wrong -import { BulkSelect } from '@patternfly/react-component-groups'; -``` - -## Implementation Rules - -### Component Usage -- ✅ **Use component groups for complex, opinionated UI patterns** -- ✅ **Reference official PatternFly and component group demos** -- ❌ **Don't reimplement existing group functionality with custom code** - -### Example Usage -```jsx -import { BulkSelect } from '@patternfly/react-component-groups/dist/dynamic/BulkSelect'; - - -``` - -### Component API Rules -- Use PatternFly naming conventions for props (e.g., `variant`, `onClick`) -- Extend PatternFly types when possible -- Document all props and usage examples -- Avoid unnecessary external dependencies - -## Contribution Guidelines -- Ensure new components are sufficiently complex and valuable -- Follow the [component structure and API rules](https://github.com/patternfly/react-component-groups#readme) -- Add unit and Cypress tests for all new components -- Document new components with markdown and usage examples - -## Accessibility Rules -- Provide proper ARIA labels and roles -- Ensure keyboard navigation and screen reader support -- Follow PatternFly accessibility best practices - -## Essential Do's and Don'ts - -### ✅ Do's -- Use dynamic imports and import required CSS -- Reference official demos and documentation -- Write accessible, well-documented components -- Use JSS for styling and follow naming conventions -- Add tests for all new functionality - -### ❌ Don'ts -- Skip CSS imports or use standard imports -- Reimplement existing group components from scratch -- Ignore accessibility or documentation requirements -- Use `pf-v6-u-XXX` utility classes (use CSS variables instead) - -## Common Issues -- **Missing styles:** Ensure CSS is imported -- **Import errors:** Use `/dist/dynamic/` paths -- **Component not found:** Check package installation and import paths -- **Accessibility:** Run a11y tests and review ARIA usage - -## Quick Reference -- [Component Groups Gallery](https://www.patternfly.org/patternfly-ai/component-groups/overview) -- [Component Groups GitHub](https://github.com/patternfly/react-component-groups) -- [Migration Guide](https://github.com/patternfly/react-component-groups/blob/main/migration.md) - -**Note:** Component group guidance takes precedence over general PatternFly patterns for these components. Always consult the latest documentation and demo source code. \ No newline at end of file diff --git a/documentation/components/README.md b/documentation/components/README.md deleted file mode 100644 index 8b472446..00000000 --- a/documentation/components/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# PatternFly React Components - -You can find documentation on PatternFly's components at [PatternFly All components documentation](https://www.patternfly.org/components/all-components) - -## Specific info on Components - -- [AboutModal](https://www.patternfly.org/components/about-modal) -- [Accordion](https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/components/accordion/accordion.md) -- [ActionList](https://www.patternfly.org/components/action-list) -- [Alert](https://www.patternfly.org/components/alert) -- [ApplicationLauncher](https://www.patternfly.org/components/application-launcher) diff --git a/documentation/components/data-display/README.md b/documentation/components/data-display/README.md deleted file mode 100644 index 53d9cad2..00000000 --- a/documentation/components/data-display/README.md +++ /dev/null @@ -1,222 +0,0 @@ -# Data Display Rules - -Essential rules for PatternFly data display components including lists, data presentation, and data view patterns. - -## Related Files -- [**Component Architecture**](../../guidelines/component-architecture.md) - Data component structure rules -- [**Layout Rules**](../layout/README.md) - Page structure patterns -- [**Table Documentation**](./table.md) - Table component rules and best practices - -## Dropdown Action Rules - -### Required Dropdown Pattern -- ✅ **Use MenuToggle with variant="plain"** - For kebab-style dropdowns -- ✅ **Configure popperProps** - Prevent clipping issues -- ✅ **Use EllipsisVIcon** - Standard kebab menu icon - -```jsx -// ✅ Required dropdown pattern -import { Dropdown, DropdownList, DropdownItem, MenuToggle, Divider } from '@patternfly/react-core'; -import { EllipsisVIcon } from '@patternfly/react-icons'; - - document.body // Prevents clipping - }} - toggle={(toggleRef) => ( - - - - )} -> - - onEdit(item)}>Edit - - onDelete(item)}>Delete - - -``` - -## Toolbar Rules - -### Required Toolbar Pattern -- ✅ **Use clearAllFilters prop** - For "Clear all filters" functionality -- ✅ **Use ToolbarFilter with labels** - Display active filters as chips -- ✅ **Use ToolbarToggleGroup** - For responsive filter collapsing -- ✅ **Show bulk actions when items selected** - Conditional bulk action UI - -```jsx -// ✅ Required toolbar pattern -import { Toolbar, ToolbarContent, ToolbarFilter, ToolbarToggleGroup } from '@patternfly/react-core'; - - - - {selectedCount > 0 && ( - - {selectedCount} selected - - - )} - } breakpoint="xl"> - - - - - - -``` - -## State Management Rules - -### Required State Patterns -- ✅ **Use Set for selection** - More efficient than arrays -- ✅ **Handle loading states** - Show spinners or skeletons -- ✅ **Handle empty states** - Show appropriate messages -- ✅ **Handle error states** - Show error messages with retry - -```jsx -// ✅ Required state management -const [selectedItems, setSelectedItems] = useState(new Set()); -const [isLoading, setIsLoading] = useState(false); -const [error, setError] = useState(null); - -if (isLoading) return ; -if (error) return ; -if (!data?.length) return ; -``` - -## Performance Rules - -### Required Optimizations -- ✅ **Use pagination for large datasets** - Better UX than virtualization -- ✅ **Memoize table rows** - React.memo for performance -- ✅ **Use useCallback for handlers** - Stable references - -```jsx -// ✅ Required for large datasets -import { Pagination } from '@patternfly/react-core'; - -// For better UX, use pagination - -``` - -## Essential Do's and Don'ts - -### ✅ Do's -- Use composable Table components (Thead, Tbody, Tr, Th, Td) -- Implement proper sorting with sort prop on Th components -- Use Checkbox components for selectable rows -- Configure dropdown positioning with popperProps -- Provide empty states for no data and filtered results -- Implement loading states with skeletons or spinners -- Use proper ARIA labels for accessibility - -### ❌ Don'ts -- Create custom table components when PatternFly Table exists -- Ignore responsive design for data tables -- Skip loading and empty states -- Forget to handle dropdown clipping issues -- Use inconsistent selection patterns -- Skip accessibility considerations for interactive elements - -## Common Issues - -### Dropdown Clipping -```jsx -// ✅ Solution: Use appendTo to prevent clipping - document.body }}> -``` - -### Performance Issues -- **1000+ rows**: Use virtualization with react-window -- **Large datasets**: Implement pagination -- **Slow rendering**: Memoize components with React.memo - -### Selection Issues -- **Use Set not Array**: More efficient for selection state -- **Handle indeterminate**: For "select all" checkbox state -- **Provide feedback**: Show selected count and bulk actions - -## Quick Reference -- **[Table Component](https://www.patternfly.org/components/table)** - Official table documentation -- **[Toolbar Component](https://www.patternfly.org/components/toolbar)** - Toolbar with filters -- **[Dropdown Component](https://www.patternfly.org/components/menus/dropdown)** - Dropdown positioning - -## Using the Data View Component - -The `@patternfly/react-data-view` component is a powerful, opinionated tool for building consistent data-driven tables and lists. It composes standard PatternFly components like `Table`, `Toolbar`, and `Pagination` into a single, streamlined API. - -### When to Use Data View -- ✅ **Use for standard list pages**: When you need to display a list of resources with common functionality like filtering, sorting, selection, and actions. -- ✅ **To enforce consistency**: Use it across your application to ensure all data tables look and behave the same. -- ❌ **Not for highly custom layouts**: If your layout deviates significantly from a standard table or list view, composing individual PatternFly components may be a better approach. - -## Data view documentation -- **[Data view](https://www.patternfly.org/extensions/data-view/overview)** - Official data view documentation -- **[Table Component](https://www.patternfly.org/extensions/data-view/table)** - Data view's table documentation and examples -- **[Toolbar Component](https://www.patternfly.org/extensions/data-view/toolbar/)** - Data view's toolbar documentation and examples - -### Required Setup - -1. **Installation**: - ```bash - npm install @patternfly/react-data-view - ``` - -2. **CSS Import**: - ```jsx - // Import required CSS in your application's entrypoint - import '@patternfly/react-data-view/dist/css/main.css'; - ``` - -3. **Component Import**: - ```jsx - // Use dynamic imports for better performance - import DataView from '@patternfly/react-data-view/dist/dynamic/DataView'; - ``` - -### Best Practices - -- **Provide stable data and columns**: For performance, memoize the `data` and `columns` props passed to `DataView`, especially if they are derived from other state. - ```jsx - const columns = useMemo(() => [...], []); - const data = useMemo(() => [...], [sourceData]); - - - ``` - -- **Leverage the built-in toolbar**: `DataView` includes a `Toolbar` with filtering capabilities. Provide filter configurations instead of building your own toolbar from scratch. - -- **Use the provided action resolver**: For row actions, use the `onRowAction` prop and provide an action resolver function. This ensures actions are handled consistently. - -### Real-World Example: OpenShift Console - -A production example of PatternFly Data View usage can be found in the OpenShift Console codebase. It's an excellent resource for seeing how `DataView` is integrated with live Kubernetes data and Redux for state management. - -- **[DataViewPodList.tsx on GitHub](https://github.com/openshift/console/blob/79d29bca8440a5ad82b5257bb0f37bc24384eb0e/frontend/public/components/data-view-poc/DataViewPodList.tsx)** - -Key integration patterns from this example include: -- Integrating Data View with live Kubernetes data and application state. -- Passing dynamic data and columns to the component. -- Handling loading, error, and empty states in a production context. -- Using PatternFly composable components for custom row rendering and actions. -- Connecting Data View to Redux or other state management solutions. - -> For advanced usage, review the linked file to see how Data View is composed with other PatternFly and application-specific components. - -> **Note:** Always consult the latest PatternFly Data View documentation and demo source code for the most up-to-date usage patterns and best practices. -- [PatternFly React Data View GitHub](https://github.com/patternfly/react-data-view) -- [PatternFly Data View NPM](https://www.npmjs.com/package/@patternfly/react-data-view) - -## Empty State Button Placement Rules - -- ✅ **Place all buttons in an EmptyState inside the `EmptyStateFooter` component.** -- ✅ **Group each row of buttons within an `EmptyStateActions` container inside the `EmptyStateFooter`.** -- ✅ **Use a separate `EmptyStateActions` for each row of actions if multiple rows are needed.** -- ❌ **Do not place buttons directly inside `EmptyState` or `EmptyStateBody`.** diff --git a/documentation/components/data-display/table.md b/documentation/components/data-display/table.md deleted file mode 100644 index 4b04ab5d..00000000 --- a/documentation/components/data-display/table.md +++ /dev/null @@ -1,190 +0,0 @@ -# Table Component Rules - -Essential rules for PatternFly table components, including usage, sorting, selection, performance, accessibility, and best practices. - -## Required Table Structure -- ✅ **Use composable Table components** - `Table`, `Thead`, `Tbody`, `Tr`, `Th`, `Td` -- ✅ **Import from @patternfly/react-table** - Not @patternfly/react-core -- ❌ **Don't create custom table components** - Use PatternFly's composable approach - -```jsx -// ✅ Correct table structure -import { Table, Thead, Tbody, Tr, Th, Td } from '@patternfly/react-table'; - - - - - - - - - - {data.map(item => ( - - - - - ))} - -
NameEmail
{item.name}{item.email}
-``` - -## Sorting Rules -- ✅ **Use sort prop on Th components** - Configure sorting via the `sort` prop -- ✅ **Manage sort state with useState** - Track sortBy state -- ✅ **Use useMemo for sorted data** - Performance optimization - -```jsx -// ✅ Required sorting pattern -const [sortBy, setSortBy] = useState({}); - - - Name - -``` - -## Selection Rules -- ✅ **Use Set for selection state** - More efficient than arrays -- ✅ **Handle indeterminate state** - For "select all" checkbox -- ✅ **Use proper ARIA labels** - For accessibility - -```jsx -// ✅ Required selection pattern -const [selectedItems, setSelectedItems] = useState(new Set()); - -const isAllSelected = selectedItems.size === data.length && data.length > 0; -const isPartiallySelected = selectedItems.size > 0 && selectedItems.size < data.length; - - -``` - -## Column and Header Management - -PatternFly provides powerful props for controlling column widths and making headers and columns "sticky" for better usability with wide or long tables. - -### Column Width Control -Use the `width` modifier on the `` component to specify column widths as a percentage of the table's total width. - -- ✅ **Use `width(percentage)`**: Best for flexible, responsive layouts. -- ❌ **Avoid fixed pixel widths**: Can break responsiveness. - -```jsx -import { Table, Thead, Tbody, Tr, Th, Td } from '@patternfly/react-table'; -import { width } from '@patternfly/react-table'; - - - - - - - - - - - {/* ... */} - -
User IDNameEmail
-``` - -### Controlling Text and Column Width -In addition to setting explicit widths, you can control how text behaves within cells using the `modifier` prop on `` and `` components. This influences column dimensions and text overflow. - -Key text modifiers include: -- **`truncate`**: Truncates text with an ellipsis. -- **`wrap`**: Forces text to wrap, which is useful for long header text. -- **`nowrap`**: Prevents text from wrapping. -- **`breakWord`**: Forces long, unbreakable strings (like URLs) to break. -- **`fitContent`**: Shrinks the column to fit its content. - -For detailed usage and code examples, see the official PatternFly documentation and the example in the PatternFly React repository. - -- [**Controlling Text in Tables (PatternFly Docs)**](https://www.patternfly.org/components/table/controlling-text) -- [**TableControllingText.tsx Example on GitHub**](https://github.com/patternfly/patternfly-react/blob/main/packages/react-table/src/components/Table/examples/TableControllingText.tsx) - -### Sticky Headers and Columns -For tables that scroll horizontally or vertically, you can make the header, specific columns, or the action column "sticky." - -- **`isStickyHeader`**: Add this prop to the `` component to make the header row stick to the top during vertical scrolling. -- **`isSticky`**: Add this prop to a ` - - - - )); - ``` - -## Build and Deployment Issues - -### Build Failures - -#### Issue: Build process fails -```bash -# Error message -npm ERR! Failed at the build script -``` - -**Solutions**: -1. **Check for TypeScript errors**: - ```bash - npx tsc --noEmit - ``` - -2. **Verify all imports**: - ```bash - # Check for unused imports - npm run lint - ``` - -3. **Clear build cache**: - ```bash - rm -rf dist/ build/ - npm run build - ``` - -#### Issue: Bundle size too large -```bash -# Warning: Bundle size exceeds recommended limit -``` - -**Solutions**: -1. **Analyze bundle**: - ```bash - npm install --save-dev webpack-bundle-analyzer - npx webpack-bundle-analyzer dist/ - ``` - -2. **Implement code splitting**: - ```jsx - const LazyComponent = React.lazy(() => import('./HeavyComponent')); - - }> - - - ``` - -3. **Tree shake unused code**: - ```javascript - // webpack.config.js - module.exports = { - optimization: { - usedExports: true, - sideEffects: false - } - }; - ``` - -## Browser Compatibility Issues - -### Cross-Browser Problems - -#### Issue: Components not working in specific browsers -```bash -# Symptoms: Features work in Chrome but not Safari/Firefox -``` - -**Solutions**: -1. **Check browser support**: - ```json - // package.json - "browserslist": [ - "> 1%", - "last 2 versions", - "not dead" - ] - ``` - -2. **Add polyfills**: - ```bash - npm install core-js - ``` - ```jsx - // index.js - import 'core-js/stable'; - ``` - -3. **Test across browsers**: - - Use browser dev tools - - Test on actual devices - - Use browser testing services - -## Debugging Strategies - -### General Debugging Approach -1. **Check Console**: Look for error messages and warnings -2. **Isolate Problem**: Create minimal reproduction case -3. **Verify Versions**: Ensure compatible package versions -4. **Check Documentation**: Reference official PatternFly docs -5. **Search Issues**: Look for similar problems in GitHub issues - -### Debug Tools -- **React DevTools**: Inspect component state and props -- **Browser DevTools**: Network, console, and element inspection -- **PatternFly DevTools**: PatternFly-specific debugging -- **Bundle Analyzer**: Analyze build output and dependencies - -### Getting Help -1. **GitHub Issues**: Search and create issues with minimal reproduction -2. **Stack Overflow**: Use `patternfly` tag for questions -3. **Community Slack**: Real-time help from community -4. **Documentation**: Always check latest official documentation - -## Prevention Strategies - -### Best Practices -- **Keep Dependencies Updated**: Regularly update PatternFly packages -- **Follow Semantic Versioning**: Use compatible version ranges -- **Test Incrementally**: Test changes in small increments -- **Use Linting**: Implement ESLint and Prettier -- **Document Issues**: Keep track of solutions for future reference - -### Code Quality -- **Type Safety**: Use TypeScript when possible -- **Testing**: Write unit tests for components -- **Code Review**: Review changes for PatternFly compliance -- **Performance Monitoring**: Track bundle size and performance metrics - -Remember: When encountering issues, always check the [official PatternFly documentation](https://www.patternfly.org/) first, then search [GitHub issues](https://github.com/patternfly/patternfly-react/issues) for similar problems. Provide specific error messages, code snippets, and version information when seeking help. \ No newline at end of file diff --git a/package.json b/package.json index dde3f926..c75b4c58 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,6 @@ }, "files": [ "dist/**/*", - "documentation/**/*", "README.md", "mcp-config-example.json" ], diff --git a/src/__tests__/__snapshots__/options.defaults.test.ts.snap b/src/__tests__/__snapshots__/options.defaults.test.ts.snap index 716948b2..542271bd 100644 --- a/src/__tests__/__snapshots__/options.defaults.test.ts.snap +++ b/src/__tests__/__snapshots__/options.defaults.test.ts.snap @@ -4,8 +4,8 @@ exports[`options defaults should return specific properties: defaults 1`] = ` { "contextPath": "/", "contextUrl": "file:///", - "docsPath": "/documentation", "docsPathSlug": "documentation:", + "docsPaths": [], "http": { "allowedHosts": [], "allowedOrigins": [], diff --git a/src/__tests__/__snapshots__/server.getResources.test.ts.snap b/src/__tests__/__snapshots__/server.getResources.test.ts.snap index 4ebe25d7..d17e5910 100644 --- a/src/__tests__/__snapshots__/server.getResources.test.ts.snap +++ b/src/__tests__/__snapshots__/server.getResources.test.ts.snap @@ -93,7 +93,7 @@ exports[`promiseQueue should execute promises in order: allSettled 1`] = ` exports[`resolveLocalPathFunction should return a consistent path, basic 1`] = `"/app/project/lorem-ipsum.md"`; -exports[`resolveLocalPathFunction should return a consistent path, documentation slug 1`] = `"/documentation/guidelines/README.md"`; +exports[`resolveLocalPathFunction should return a consistent path, documentation slug 1`] = `"/app/project/documentation/guidelines/README.md"`; exports[`resolveLocalPathFunction should return a consistent path, relative path with valid navigation 1`] = `"/app/project/file.md"`; diff --git a/src/__tests__/__snapshots__/tool.patternFlyDocs.test.ts.snap b/src/__tests__/__snapshots__/tool.patternFlyDocs.test.ts.snap index bcc0f173..45f6df55 100644 --- a/src/__tests__/__snapshots__/tool.patternFlyDocs.test.ts.snap +++ b/src/__tests__/__snapshots__/tool.patternFlyDocs.test.ts.snap @@ -14,4 +14,4 @@ exports[`usePatternFlyDocsTool, callback should attempt to parse parameters, sin exports[`usePatternFlyDocsTool, callback should attempt to parse parameters, with invalid urlList 1`] = `"# Content for invalid-path"`; -exports[`usePatternFlyDocsTool, callback should attempt to parse parameters, with name and actual path 1`] = `"# Documentation for React Chatbot (v6) [AI Guidance]"`; +exports[`usePatternFlyDocsTool, callback should attempt to parse parameters, with name and actual path 1`] = `"# Content for documentation:chatbot/README.md"`; diff --git a/src/__tests__/__snapshots__/tool.searchPatternFlyDocs.test.ts.snap b/src/__tests__/__snapshots__/tool.searchPatternFlyDocs.test.ts.snap index d3eae249..399121e9 100644 --- a/src/__tests__/__snapshots__/tool.searchPatternFlyDocs.test.ts.snap +++ b/src/__tests__/__snapshots__/tool.searchPatternFlyDocs.test.ts.snap @@ -10,9 +10,9 @@ exports[`searchPatternFlyDocsTool should have a consistent return structure: str exports[`searchPatternFlyDocsTool, callback should parse parameters, default: search 1`] = `"# Search results for "Button". Showing 2 exact matches."`; -exports[`searchPatternFlyDocsTool, callback should parse parameters, with "*" searchQuery all: search 1`] = `"# Search results for "all" resources. Only showing the first 10 results. There are 764 potential match variations. Try searching with a more specific query."`; +exports[`searchPatternFlyDocsTool, callback should parse parameters, with "*" searchQuery all: search 1`] = `"# Search results for "all" resources. Only showing the first 10 results. There are 798 potential match variations. Try searching with a more specific query."`; -exports[`searchPatternFlyDocsTool, callback should parse parameters, with "all" searchQuery all: search 1`] = `"# Search results for "all" resources. Only showing the first 10 results. There are 764 potential match variations. Try searching with a more specific query."`; +exports[`searchPatternFlyDocsTool, callback should parse parameters, with "all" searchQuery all: search 1`] = `"# Search results for "all" resources. Only showing the first 10 results. There are 798 potential match variations. Try searching with a more specific query."`; exports[`searchPatternFlyDocsTool, callback should parse parameters, with explicit valid version: search 1`] = `"# Search results for "Button". Showing 2 exact matches."`; diff --git a/src/__tests__/docs.json.test.ts b/src/__tests__/docs.json.test.ts index c6a8f85a..13b02858 100644 --- a/src/__tests__/docs.json.test.ts +++ b/src/__tests__/docs.json.test.ts @@ -2,24 +2,46 @@ import docs from '../docs.json'; describe('docs.json', () => { it('should have metadata reflective of its content and unique links per each entry', () => { + const linkMap = new Map(); const allLinks = new Set(); const baseHashes = new Set(); - const flatDocs = Object.values(docs.docs).flat(); let totalDocs = 0; - flatDocs.forEach(entry => { - totalDocs += 1; - allLinks.add(entry.path); - - if (entry.path.includes('documentation:')) { - baseHashes.add('documentation:'); - } else if (/^https:\/\/raw\.githubusercontent\.com\/patternfly\/p[a-zA-Z0-9-]+\//.test(entry.path)) { - baseHashes.add(entry.path.split(/\/patternfly\/p[a-zA-Z0-9-]+\//)[1]?.split('/')[0]); - } else { - baseHashes.add(`new-resource-${entry.path}`); - } + Object.entries(docs.docs).forEach(([key, entries]) => { + entries.forEach(entry => { + totalDocs += 1; + allLinks.add(entry.path); + const path = entry.path; + + if (!linkMap.has(path)) { + linkMap.set(path, []); + } + + linkMap.get(path)?.push(`${key}: ${entry.displayName} (${entry.category})`); + + if (entry.path.includes('documentation:')) { + baseHashes.add('documentation:'); + } else if (/^https:\/\/raw\.githubusercontent\.com\/patternfly\/[a-zA-Z0-9-]+\//.test(entry.path)) { + baseHashes.add(entry.path.split(/\/patternfly\/[a-zA-Z0-9-]+\//)[1]?.split('/')[0]); + } else { + baseHashes.add(`new-resource-${entry.path}`); + } + }); }); + const duplicates = Array.from(linkMap.entries()) + .filter(([_, occurrences]) => occurrences.length > 1); + + try { + expect(duplicates.length).toBe(0); + } catch { + const message = duplicates + .map(([path, occurrences]) => `Duplicate path: ${path}\nFound in:\n - ${occurrences.join('\n - ')}`) + .join('\n\n'); + + throw new Error(`Found ${duplicates.length} duplicate links in docs.json:\n\n${message}`); + } + expect(docs.meta.totalEntries).toBeDefined(); expect(docs.meta.totalDocs).toBeDefined(); expect(Object.entries(docs.docs).length).toBe(docs.meta.totalEntries); @@ -27,7 +49,7 @@ describe('docs.json', () => { /** * Confirm we have limited hashes, avoid variation within pf versions * If this increases, hashes need to be realigned. Do not randomly change this value. - * 1 (v6 org) + 1 (v6 react) + 1 (v5 org) + 1 (codemods) + 1 (local) + * 1 (v6 org) + 1 (v6 react) + 1 (v5 org) + 1 (codemods) + 1 (ai-helpers) */ expect(baseHashes.size).toBe(5); @@ -41,7 +63,7 @@ describe('docs.json', () => { * Confirm unique links against metadata totals * Update the JSON metadata accordingly */ - expect(allLinks.size).toBe(flatDocs.length); + expect(allLinks.size).toBe(linkMap.size); expect(allLinks.size).toBe(docs.meta.totalDocs); }); }); diff --git a/src/__tests__/server.getResources.test.ts b/src/__tests__/server.getResources.test.ts index 53b4ed92..45f07b54 100644 --- a/src/__tests__/server.getResources.test.ts +++ b/src/__tests__/server.getResources.test.ts @@ -10,6 +10,7 @@ import { loadFileFetch, resolveLocalPathFunction } from '../server.getResources'; +import { runWithOptions } from '../options.context'; import { type GlobalOptions } from '../options'; import { DEFAULT_OPTIONS } from '../options.defaults'; @@ -254,7 +255,7 @@ describe('resolveLocalPathFunction', () => { path: './subdir/../file.md' } ])('should return a consistent path, $description', ({ path }) => { - const result = resolveLocalPathFunction(path, undefined, { ...DEFAULT_OPTIONS, contextPath: '/app/project' }); + const result = resolveLocalPathFunction(path, undefined, { ...DEFAULT_OPTIONS, contextPath: '/app/project', docsPaths: ['/app/project/documentation'] }); expect(result).toMatchSnapshot(); }); @@ -281,7 +282,7 @@ describe('resolveLocalPathFunction', () => { shouldThrow: 'Access denied' } ])('should return a consistent path or throw, $description', ({ path, shouldThrow }) => { - expect(() => resolveLocalPathFunction(path, undefined, { ...DEFAULT_OPTIONS, contextPath: '/app/project' })).toThrow(shouldThrow); + expect(() => resolveLocalPathFunction(path, undefined, { ...DEFAULT_OPTIONS, contextPath: '/app/project', docsPaths: ['/app/project/documentation'] })).toThrow(shouldThrow); }); }); @@ -313,7 +314,7 @@ describe('loadFileFetch', () => { readLocalFileFunction.memo = mockReadCall; fetchUrlFunction.memo = mockFetchCall; - const result = await loadFileFetch(pathUrl); + const result = await runWithOptions({ ...DEFAULT_OPTIONS, docsPaths: ['/app/project/documentation'], contextPath: '/app/project' }, () => loadFileFetch(pathUrl)); expect(mockFetchCall).toHaveBeenCalledTimes(expectedIsFetch ? 1 : 0); expect(mockReadCall).toHaveBeenCalledTimes(expectedIsFetch ? 0 : 1); diff --git a/src/docs.json b/src/docs.json index db4b41de..e694b249 100644 --- a/src/docs.json +++ b/src/docs.json @@ -1,9 +1,9 @@ { "version": "1", - "generated": "2026-03-05T00:00:00.000Z", + "generated": "2026-03-09T00:00:00.000Z", "meta": { - "totalEntries": 130, - "totalDocs": 311, + "totalEntries": 129, + "totalDocs": 320, "source": "patternfly-mcp-internal" }, "docs": { @@ -1847,6 +1847,16 @@ "source": "github", "path": "https://raw.githubusercontent.com/patternfly/patternfly-react/476782a298df81cb78de7f3cd804f3ff8f33993c/packages/react-table/src/components/Table/examples/Table.md", "version": "v6" + }, + { + "displayName": "Table Rules", + "description": "Table usage and best practices for PatternFly React.", + "pathSlug": "table-rules", + "section": "components", + "category": "react", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/components/data-display/table.md", + "version": "v6" } ], "Tabs": [ @@ -2666,8 +2676,8 @@ "pathSlug": "charts", "section": "guidelines", "category": "react", - "source": "local", - "path": "documentation:charts/README.md", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/charts/README.md", "version": "v6" } ], @@ -2678,20 +2688,8 @@ "pathSlug": "chatbot", "section": "guidelines", "category": "react", - "source": "local", - "path": "documentation:chatbot/README.md", - "version": "v6" - } - ], - "ComponentGroups": [ - { - "displayName": "Component Groups", - "description": "AI guidance for PatternFly React Component Groups.", - "pathSlug": "component-groups", - "section": "guidelines", - "category": "react", - "source": "local", - "path": "documentation:component-groups/README.md", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/chatbot/README.md", "version": "v6" } ], @@ -2702,28 +2700,28 @@ "pathSlug": "guidelines", "section": "guidelines", "category": "react", - "source": "local", - "path": "documentation:guidelines/README.md", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/guidelines/README.md", "version": "v6" }, { - "displayName": "React Components", - "description": "AI guidance for PatternFly React Components.", - "pathSlug": "components", + "displayName": "Styling Standards", + "description": "CSS and styling requirements for PatternFly React.", + "pathSlug": "styling-standards", "section": "guidelines", "category": "react", - "source": "local", - "path": "documentation:components/README.md", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/guidelines/styling-standards.md", "version": "v6" }, { - "displayName": "React Resources", - "description": "AI guidance for PatternFly React Resources.", - "pathSlug": "resources", + "displayName": "AI Prompt Guidance", + "description": "How to write effective AI prompts for PatternFly development.", + "pathSlug": "ai-prompt-guidance", "section": "guidelines", "category": "react", - "source": "local", - "path": "documentation:resources/README.md", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/guidelines/ai-prompt-guidance.md", "version": "v6" }, { @@ -2732,8 +2730,38 @@ "pathSlug": "setup", "section": "guidelines", "category": "react", - "source": "local", - "path": "documentation:setup/README.md", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/setup/README.md", + "version": "v6" + }, + { + "displayName": "Development Environment", + "description": "AI guidance for configuration of development tools and environment settings for PatternFly React development.", + "pathSlug": "development-environment", + "section": "guidelines", + "category": "react", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/setup/development-environment.md", + "version": "v6" + }, + { + "displayName": "Quick Start", + "description": "Essential setup steps for PatternFly React projects.", + "pathSlug": "quick-start", + "section": "guidelines", + "category": "react", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/setup/quick-start.md", + "version": "v6" + }, + { + "displayName": "External Links", + "description": "Comprehensive list of official PatternFly documentation and resources.", + "pathSlug": "external-links", + "section": "resources", + "category": "react", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/resources/external-links.md", "version": "v6" }, { @@ -2742,8 +2770,58 @@ "pathSlug": "troubleshooting", "section": "guidelines", "category": "react", - "source": "local", - "path": "documentation:troubleshooting/README.md", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/troubleshooting/common-issues.md", + "version": "v6" + }, + { + "displayName": "Component Architecture", + "description": "AI guidance for structuring PatternFly React components, managing state, and helping performance.", + "pathSlug": "component-architecture", + "section": "guidelines", + "category": "react", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/guidelines/component-architecture.md", + "version": "v6" + }, + { + "displayName": "Quick Deployment Guide for Prototypes", + "description": "AI guidance for simple, fast methods for building and deploying your React application so you can share a live prototype with others.", + "pathSlug": "deployment-guide", + "section": "guidelines", + "category": "react", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/guidelines/deployment-guide.md", + "version": "v6" + }, + { + "displayName": "Component Groups", + "description": "AI guidance for PatternFly React Component Groups.", + "pathSlug": "component-groups", + "section": "guidelines", + "category": "react", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/component-groups/README.md", + "version": "v6" + }, + { + "displayName": "Data Display", + "description": "AI guidance for PatternFly data display components including lists, data presentation, and data view patterns.", + "pathSlug": "data-display", + "section": "guidelines", + "category": "react", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/components/data-display/README.md", + "version": "v6" + }, + { + "displayName": "Layout Components", + "description": "AI guidance for PatternFly layout components and page structure patterns for building consistent application layouts.", + "pathSlug": "layout-components", + "section": "guidelines", + "category": "react", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/components/layout/README.md", "version": "v6" } ], @@ -3375,6 +3453,16 @@ "source": "github", "path": "https://raw.githubusercontent.com/patternfly/patternfly-org/2d5fec39ddb8aa32ce78c9a63cdfc1653692b193/packages/documentation-site/patternfly-docs/content/get-started/develop.md", "version": "v6" + }, + { + "displayName": "PatternFly React Development Rules", + "description": "Essential rules and guidelines for AI coders working with PatternFly React applications.", + "pathSlug": "development-rules", + "section": "get-started", + "category": "development-guidelines", + "source": "github", + "path": "https://raw.githubusercontent.com/patternfly/ai-helpers/5b010163ea2a7537fbb6431d262fc6db72ec7a73/docs/README.md", + "version": "v6" } ] } diff --git a/src/options.defaults.ts b/src/options.defaults.ts index cd2cf68f..be052a44 100644 --- a/src/options.defaults.ts +++ b/src/options.defaults.ts @@ -1,4 +1,4 @@ -import { basename, join, resolve } from 'node:path'; +import { basename, resolve } from 'node:path'; import { pathToFileURL } from 'node:url'; import packageJson from '../package.json'; import { type ToolModule } from './server.toolsUser'; @@ -11,7 +11,7 @@ import { type ToolModule } from './server.toolsUser'; * @template TLogOptions The logging options type, defaulting to LoggingOptions. * @property contextPath - Current working directory. * @property contextUrl - Current working directory URL. - * @property docsPath - Path to the documentation directory. + * @property docsPaths - List of allowed local documentation directories handled by `docsPathSlug` * @property docsPathSlug - Local docs slug. Used for resolving local stored documentation. * @property isHttp - Flag indicating whether the server is running in HTTP mode. * @property {HttpOptions} http - HTTP server options. @@ -30,6 +30,8 @@ import { type ToolModule } from './server.toolsUser'; * @property repoName - Name of the repository. * @property {RepoResources} repoResources - Repository resources. * @property {typeof RESOURCE_MEMO_OPTIONS} resourceMemoOptions - Resource-level memoization options. + * @property resourceModules - Array for programmatic registration of resource provider modules, similar to `toolModules` but + * for MCP resources and currently only internal. * @property separator - Default string delimiter. * @property {StatsOptions} stats - Stats options. * @property {typeof TOOL_MEMO_OPTIONS} toolMemoOptions - Tool-specific memoization options. @@ -42,7 +44,7 @@ import { type ToolModule } from './server.toolsUser'; interface DefaultOptions { contextPath: string; contextUrl: string; - docsPath: string; + docsPaths: string[]; docsPathSlug: string; http: HttpOptions; isHttp: boolean; @@ -480,7 +482,7 @@ const getNodeMajorVersion = (nodeVersion = process.versions.node) => { const DEFAULT_OPTIONS: DefaultOptions = { contextPath: (process.env.NODE_ENV === 'local' && '/') || resolve(process.cwd()), contextUrl: pathToFileURL((process.env.NODE_ENV === 'local' && '/') || resolve(process.cwd())).href, - docsPath: (process.env.NODE_ENV === 'local' && '/documentation') || join(resolve(process.cwd()), 'documentation'), + docsPaths: [], docsPathSlug: 'documentation:', isHttp: false, http: HTTP_OPTIONS, diff --git a/src/server.getResources.ts b/src/server.getResources.ts index b5e49671..7b33151d 100644 --- a/src/server.getResources.ts +++ b/src/server.getResources.ts @@ -171,10 +171,19 @@ const resolveLocalPathFunction = (path: string, { sep: separator = sep } = {}, o }; if (path.startsWith(documentationPrefix)) { - const base = options.docsPath; - const resolved = resolve(base, path.slice(documentationPrefix.length)); + const subPath = path.slice(documentationPrefix.length); + const failedBasePaths = []; - return confirmThenReturnResolvedBase(base, resolved); + for (const base of options.docsPaths) { + const resolved = resolve(base, subPath); + + try { + return confirmThenReturnResolvedBase(base, resolved); + } catch { + failedBasePaths.push(base); + } + } + throw new Error(`Access denied: path ${path} does not match any allowed documentation directories ${failedBasePaths.join(', ')}`); } if (isUrl(path)) { diff --git a/tests/e2e/__snapshots__/httpTransport.test.ts.snap b/tests/e2e/__snapshots__/httpTransport.test.ts.snap index 4dd96cd1..dedef4b1 100644 --- a/tests/e2e/__snapshots__/httpTransport.test.ts.snap +++ b/tests/e2e/__snapshots__/httpTransport.test.ts.snap @@ -15,40 +15,6 @@ exports[`Builtin resources, HTTP transport should expose expected resources and } `; -exports[`Builtin tools, HTTP transport should concatenate headers and separator with two local files 1`] = ` -"# Documentation for React Components (v6) [AI Guidance] -Source: documentation:components/README.md - -# PatternFly Development Rules - This is a generated offline fixture used by the MCP external URLs test. - - Essential rules and guidelines working with PatternFly applications. - - ## Quick Navigation - - ### 🚀 Setup & Environment - - **Setup Rules** - Project initialization requirements - - **Quick Start** - Essential setup steps - - **Environment Rules** - Development configuration - ---- - -# Content for documentation/guidelines/README.md -Source: documentation/guidelines/README.md - -# PatternFly Development Rules - This is a generated offline fixture used by the MCP external URLs test. - - Essential rules and guidelines working with PatternFly applications. - - ## Quick Navigation - - ### 🚀 Setup & Environment - - **Setup Rules** - Project initialization requirements - - **Quick Start** - Essential setup steps - - **Environment Rules** - Development configuration" -`; - exports[`Builtin tools, HTTP transport should concatenate headers and separator with two remote files 1`] = ` "# Content for https://www.patternfly.org/notARealPath/AboutModal.md Source: https://www.patternfly.org/notARealPath/AboutModal.md diff --git a/tests/e2e/__snapshots__/stdioTransport.test.ts.snap b/tests/e2e/__snapshots__/stdioTransport.test.ts.snap index cbd00944..af65ddc8 100644 --- a/tests/e2e/__snapshots__/stdioTransport.test.ts.snap +++ b/tests/e2e/__snapshots__/stdioTransport.test.ts.snap @@ -15,40 +15,6 @@ exports[`Builtin resources, STDIO should expose expected resources and templates } `; -exports[`Builtin tools, STDIO should concatenate headers and separator with two local files 1`] = ` -"# Documentation for React Components (v6) [AI Guidance] -Source: documentation:components/README.md - -# PatternFly Development Rules - This is a generated offline fixture used by the MCP external URLs test. - - Essential rules and guidelines working with PatternFly applications. - - ## Quick Navigation - - ### 🚀 Setup & Environment - - **Setup Rules** - Project initialization requirements - - **Quick Start** - Essential setup steps - - **Environment Rules** - Development configuration - ---- - -# Content for documentation/guidelines/README.md -Source: documentation/guidelines/README.md - -# PatternFly Development Rules - This is a generated offline fixture used by the MCP external URLs test. - - Essential rules and guidelines working with PatternFly applications. - - ## Quick Navigation - - ### 🚀 Setup & Environment - - **Setup Rules** - Project initialization requirements - - **Quick Start** - Essential setup steps - - **Environment Rules** - Development configuration" -`; - exports[`Builtin tools, STDIO should concatenate headers and separator with two remote files 1`] = ` "# Content for http://127.0.0.1:5010/notARealPath/AboutModal.md Source: http://127.0.0.1:5010/notARealPath/AboutModal.md diff --git a/tests/e2e/httpTransport.test.ts b/tests/e2e/httpTransport.test.ts index feeb48ab..37b41a0a 100644 --- a/tests/e2e/httpTransport.test.ts +++ b/tests/e2e/httpTransport.test.ts @@ -78,7 +78,8 @@ describe('Builtin tools, HTTP transport', () => { expect({ toolNames }).toMatchSnapshot('tools'); }); - it('should concatenate headers and separator with two local files', async () => { + it('should concatenate headers and separator with two fixture server routes', async () => { + const URL_MOCK = `${FETCH_MOCK?.fixture?.baseUrl}/`; const req = { jsonrpc: '2.0', id: 1, @@ -87,8 +88,9 @@ describe('Builtin tools, HTTP transport', () => { name: 'usePatternFlyDocs', arguments: { urlList: [ - 'documentation/guidelines/README.md', - 'documentation:components/README.md' + // README.md matches /README\.md/ route in fetchMock + `${URL_MOCK}README.md`, + `${URL_MOCK}AboutModal.md` ] } } @@ -97,8 +99,10 @@ describe('Builtin tools, HTTP transport', () => { const response = await CLIENT?.send(req); const text = response?.result?.content?.[0]?.text || ''; + expect(text.includes('AboutModal.md')).toBe(true); + expect(text.includes('This is a test document for mocking remote HTTP requests')).toBe(true); + expect(text.includes('README.md')).toBe(true); expect(text.includes('This is a generated offline fixture')).toBe(true); - expect(text).toMatchSnapshot(); }); it('should concatenate headers and separator with two remote files', async () => { diff --git a/tests/e2e/stdioTransport.test.ts b/tests/e2e/stdioTransport.test.ts index eadf9a6b..49b4b075 100644 --- a/tests/e2e/stdioTransport.test.ts +++ b/tests/e2e/stdioTransport.test.ts @@ -76,7 +76,7 @@ describe('Builtin tools, STDIO', () => { expect({ toolNames }).toMatchSnapshot(); }); - it('should concatenate headers and separator with two local files', async () => { + it('should concatenate headers and separator with two fixture server routes', async () => { const req = { jsonrpc: '2.0', id: 1, @@ -85,8 +85,9 @@ describe('Builtin tools, STDIO', () => { name: 'usePatternFlyDocs', arguments: { urlList: [ - 'documentation/guidelines/README.md', - 'documentation:components/README.md' + // README.md matches /README\.md/ route in fetchMock + `${URL_MOCK}README.md`, + `${URL_MOCK}AboutModal.md` ] } } @@ -95,8 +96,10 @@ describe('Builtin tools, STDIO', () => { const response = await CLIENT.send(req); const text = response?.result?.content?.[0]?.text || ''; + expect(text.includes('AboutModal.md')).toBe(true); + expect(text.includes('This is a test document for mocking remote HTTP requests')).toBe(true); + expect(text.includes('README.md')).toBe(true); expect(text.includes('This is a generated offline fixture')).toBe(true); - expect(text).toMatchSnapshot(); }); it('should concatenate headers and separator with two remote files', async () => { diff --git a/tests/e2e/utils/fetchMock.ts b/tests/e2e/utils/fetchMock.ts index 165f4a1e..f9c01908 100644 --- a/tests/e2e/utils/fetchMock.ts +++ b/tests/e2e/utils/fetchMock.ts @@ -313,6 +313,8 @@ export const setupFetchMock = async (options: FetchMockSetup = {}): Promise
` or `` component to make an entire column sticky during horizontal scrolling. This is commonly used for the first column (e.g., selection checkbox or ID), or last column (e.g. columns containing actions menus). - -```jsx -// ✅ Sticky header, first column, and action column -import { Table, Thead, Tbody, Tr, Th, Td } from '@patternfly/react-table'; - - - - - - - {/* ... more columns */} - - - - - {data.map(item => ( - - - - {/* ... more cells */} - - - ))} - -
IDNameActions
{item.id}{item.name} - -
-``` - -## Performance Rules -- ✅ **Use Skeleton for loading states** - Provide visual feedback -- ✅ **Ensure responsive behavior** - Test on multiple screen sizes -- ✅ **Use pagination for large datasets** - Better UX than virtualization -- ✅ **Memoize table rows** - React.memo for performance -- ✅ **Use useCallback for handlers** - Stable references - -```jsx -// ✅ Required for large datasets -import { Pagination } from '@patternfly/react-core'; - -// For better UX, use pagination - -``` - -## Essential Do's and Don'ts - -### ✅ Do's -- Use composable Table components (Thead, Tbody, Tr, Th, Td) -- Implement proper sorting with sort prop on Th components -- Use Checkbox components for selectable rows -- Configure dropdown positioning with popperProps -- Provide empty states for no data and filtered results -- Implement loading states with skeletons or spinners -- Use proper ARIA labels for accessibility - -### ❌ Don'ts -- Create custom table components when PatternFly Table exists -- Ignore responsive design for data tables -- Skip loading and empty states -- Forget to handle dropdown clipping issues -- Use inconsistent selection patterns -- Skip accessibility considerations for interactive elements - -## Common Issues - -### Dropdown Clipping -```jsx -// ✅ Solution: Use appendTo to prevent clipping - document.body }}> -``` - -### Selection Issues -- **Use Set not Array**: More efficient for selection state -- **Handle indeterminate**: For "select all" checkbox state -- **Provide feedback**: Show selected count and bulk actions - -## Quick Reference -- **[Table Component](https://www.patternfly.org/components/table)** - Official table documentation \ No newline at end of file diff --git a/documentation/components/layout/README.md b/documentation/components/layout/README.md deleted file mode 100644 index d6dcf062..00000000 --- a/documentation/components/layout/README.md +++ /dev/null @@ -1,167 +0,0 @@ -# Layout Components - -This section covers PatternFly layout components and page structure patterns for building consistent application layouts. - -> **Note:** For up-to-date code examples, this documentation now links directly to the official PatternFly documentation and the PatternFly React GitHub repository. Inline code has been replaced with links to ensure you always see the latest patterns and best practices. **All layout examples should use PatternFly React layout components (e.g., Grid, GridItem, Flex, FlexItem) instead of divs with utility classes.** - -## Introduction - -PatternFly layout components provide the foundation for structuring application pages and organizing content. These components ensure consistent spacing, responsive behavior, and proper semantic structure across your application. - -## Reference Documentation - -- [PatternFly Layouts on PatternFly.org](https://www.patternfly.org/layouts/about-layouts) -- [PatternFly React GitHub Repository](https://github.com/patternfly/patternfly-react) - -> 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. - -## Related Files - -- [**Component Architecture**](../../guidelines/component-architecture.md) - Component structure patterns -- [**Styling Standards**](../../guidelines/styling-standards.md) - Layout styling guidelines - -## Core Layout Components - -### PageSection Component - -The [`PageSection`](https://www.patternfly.org/components/page/page-section) component is the primary building block for page content structure. It is highly versatile and supports multiple variants, padding options, and responsive configurations. - -For detailed examples of all its features, refer to the official documentation. - -- [**PageSection Official Docs**](https://www.patternfly.org/components/page/page-section) -- [**PageSection Code Examples on GitHub**](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/components/PageSection/examples) - -## Common Layout Patterns - -This section describes common page layout patterns and links to their official documentation and examples. - -### Standard Page Layout -A standard page layout typically consists of a page title, an optional toolbar for actions, and a main content area. - -- [**Page Layout Documentation**](https://www.patternfly.org/components/page/design-guidelines) -- [**Page Component Examples on GitHub**](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/components/Page/examples) - -### Dashboard Layout -A dashboard is used to display a high-level overview of system status and key metrics using a grid of cards and charts. - -- [**Dashboard Layout Documentation**](https://www.patternfly.org/layouts/dashboard) -- [**Grid Layout Examples on GitHub**](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/layouts/Grid/examples) - -### Form Layout -Forms should be presented clearly within a card or a dedicated page section, often in a two-column layout on larger screens to separate the form from supplementary help text. - -- [**Form Component Documentation**](https://www.patternfly.org/components/form) -- [**Form Code Examples on GitHub**](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/components/Form/examples) - -## Grid System Integration - -The PatternFly `Grid` and `GridItem` components are used to create flexible, responsive layouts. For detailed examples of basic and responsive grid patterns, refer to the official documentation. - -- [**Grid Layout Documentation**](https://www.patternfly.org/layouts/grid) -- [**Grid Code Examples on GitHub**](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/layouts/Grid/examples) - -## Responsive Design Considerations - -Use the `Flex` and `FlexItem` components along with breakpoint modifiers to create layouts that adapt to different screen sizes. A mobile-first approach is recommended, where the default layout is for mobile and is enhanced for larger screens. - -- [**Flex Layout Documentation**](https://www.patternfly.org/layouts/flex) -- [**Flex Code Examples on GitHub**](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/layouts/Flex/examples) -- [**Responsive Utilities Documentation**](https://www.patternfly.org/utilities/responsive) - -## Accessibility Considerations - -### Semantic Structure -Always use the correct heading hierarchy (`

`, `

`, `

`, etc.) to structure your page content logically. Use the `component` prop on PatternFly components to render the correct HTML element. - -### Skip to Content and Back to Top -For accessible and user-friendly navigation on long pages, PatternFly provides the `SkipToContent` and `BackToTop` components, which are integrated directly into the `Page` component. - -- **`SkipToContent`**: Allows keyboard users to bypass navigation and jump directly to the main content area. -- **`BackToTop`**: Allows all users to quickly return to the top of the page after scrolling. - -**Best Practices**: -- ✅ Use `SkipToContent` on every page with navigation, linking its `href` to the main content `id`. -- ✅ Use `BackToTop` on any page that requires significant scrolling, linking `scrollableSelector` to the main content `id`. -- ✅ Assign the `mainContainerId` on the `Page` component to ensure both helpers work correctly. - -```jsx -// ✅ Correct: Use SkipToContent and BackToTop together -import { Page, PageSection, SkipToContent, BackToTop } from '@patternfly/react-core'; - -const AppLayout = () => { - const mainContentId = "main-content"; - - return ( - Skip to content} - backToTop={} - > - - {/* ... long content that requires scrolling ... */} - - - ); -}; -``` - -**Reference Documentation**: -- [SkipToContent Component Docs](https://www.patternfly.org/components/skip-to-content) -- [BackToTop Component Docs](https://www.patternfly.org/components/back-to-top) - -### ARIA Landmarks -Use ARIA landmarks to define regions of a page like `main`, `aside`, `nav`, etc. This can be done by passing the `component` prop to `PageSection`. - -- [**ARIA Landmarks in PatternFly**](https://www.patternfly.org/accessibility/aria-landmarks) - -## Performance Optimization - -### Lazy Loading and Conditional Rendering -For performance-critical applications, use standard React patterns like lazy loading and conditional rendering to defer loading of non-critical components or sections of the page. - -- [**React Docs: Code-Splitting and Lazy Loading**](https://react.dev/reference/react/lazy) -- [**React Docs: Conditional Rendering**](https://react.dev/learn/conditional-rendering) - -## Best Practices - -- ✅ Use PageSection for all major page areas -- ✅ Follow consistent page structure patterns -- ✅ Implement responsive design from mobile-first -- ✅ Use proper semantic HTML structure -- ✅ Maintain consistent spacing with PatternFly utilities -- ✅ Test layouts across different screen sizes -- ✅ Use hasBodyWrapper for standard content padding - -- ❌ Skip PageSection for page structure -- ❌ Mix layout systems inconsistently -- ❌ Ignore responsive design requirements -- ❌ Use custom CSS when PatternFly layout classes exist -- ❌ Create overly complex nested layouts -- ❌ Forget accessibility considerations -- ❌ Hardcode spacing values instead of using utilities - -## Common Layout Issues - -For troubleshooting, see [Common Issues](../../troubleshooting/common-issues.md#layout-issues). - -## Valid PatternFly Page Layout (v6+) - -A valid PatternFly v6+ application layout is built by composing the `Page`, `Masthead`, `PageSidebar`, and `PageSection` components. The `Page` component acts as the root, and other major elements like the masthead and sidebar are passed in as props. - -For a complete, working example of a full application layout, refer to the official PatternFly documentation. - -- [**Page Component Documentation & Examples**](https://www.patternfly.org/components/page) -- [**Page Component Code Examples on GitHub**](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/components/Page/examples) - -### Layout Summary Table - -| Layout Element | PatternFly Component(s) | Notes | -|---------------|------------------------|-------| -| Root | `Page` | Use `masthead`, `sidebar`, `breadcrumb` props | -| Masthead | `Masthead`, `MastheadMain`, `MastheadBrand`, etc. | Compose for logo, toggles, user menu | -| Sidebar | `PageSidebar`, `PageSidebarBody`, `Nav` | Use for navigation | -| Main Content | `PageSection`, `Title`, `Content` | Use for each page/view | -| Breadcrumbs | `Breadcrumb` | Pass as `breadcrumb` prop to `Page` | -| Page Header | *No `PageHeader`* | Use `PageSection` + `Title` instead | - -> **Note:** `PageHeader` is not a PatternFly component in v6+. Use `PageSection`, `Title`, and layout components instead. diff --git a/documentation/core/README.md b/documentation/core/README.md deleted file mode 100644 index 8e55cb50..00000000 --- a/documentation/core/README.md +++ /dev/null @@ -1,67 +0,0 @@ -# PatternFly React Development Rules - -> **Starting a new project?** -> 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. - -Essential rules and guidelines for AI coders working with PatternFly React applications. - -## Quick Navigation - -### 🚀 Setup & Environment -- [**Setup Rules**](./setup/README.md) - Project initialization requirements -- [**Quick Start**](./setup/quick-start.md) - Essential setup steps -- [**Environment Rules**](./setup/development-environment.md) - Development configuration - -### 📚 Core Rules -- [**PatternFly Guidelines**](./guidelines/README.md) - Core development principles -- [**Component Rules**](./guidelines/component-architecture.md) - Component structure requirements -- [**Styling Rules**](./guidelines/styling-standards.md) - CSS and styling requirements -- [**AI Prompt Guidance**](./guidelines/ai-prompt-guidance.md) - How to write effective AI prompts -- [**Deployment Guide**](./guidelines/deployment-guide.md) - How to deploy prototypes - -### 🧩 Component Rules -- [**Components Rules**](./components/README.md) - Page structure requirements -- [**Layout Rules**](./components/layout/README.md) - Page structure requirements -- [**Table Component Rules**](./components/data-display/table.md) - Table usage and best practices -- [**Data View Component Rules**](./components/data-display/README.md) - Data view usage and best practices - -### 🔧 Troubleshooting -- [**Common Issues**](./troubleshooting/common-issues.md) - Problem resolution rules - -### 📖 Resources -- [**External Links**](./resources/external-links.md) - Official documentation links - -## Usage Rules for AI Coders - -1. **Always use PatternFly v6** - Use `pf-v6-` prefixed classes only -2. **Component-first approach** - Use PatternFly components before custom solutions -3. **Consult documentation** - Reference [PatternFly.org](https://www.patternfly.org/) for examples -4. **Follow accessibility** - Implement proper ARIA labels and keyboard navigation -5. **Use utility classes** - Prefer PatternFly utilities over custom CSS -6. **Handle states** - Always implement loading, error, and empty states - -## ⚠️ Common AI Coding Issues Addressed - -Based on feedback, these rules prevent frequent AI-generated errors: - -- **❌ No CSS modules syntax** - `className={styles.x}` doesn't work in this project -- **❌ No non-existent components** - Verify components exist before using -- **❌ No inline styles for layout** - Use PatternFly utilities instead -- **✅ Chart imports must include `/victory`** - Critical for chart components -- **✅ Always include accessibility attributes** - Keyboard navigation and ARIA labels -- **✅ Use specific, detailed prompts** - See [AI Prompt Guidance](./guidelines/ai-prompt-guidance.md) - -## Documentation Structure - -Each file contains: -- **Rules** - Specific requirements to follow -- **Do's and Don'ts** - Clear guidance on what to avoid -- **Links** - References to official PatternFly documentation -- **Quick examples** - Minimal code patterns when needed - -## Reference Documentation - -- [PatternFly.org](https://www.patternfly.org/) -- [PatternFly React GitHub Repository](https://github.com/patternfly/patternfly-react) - -> 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. \ No newline at end of file diff --git a/documentation/guidelines/README.md b/documentation/guidelines/README.md deleted file mode 100644 index 6e01a639..00000000 --- a/documentation/guidelines/README.md +++ /dev/null @@ -1,86 +0,0 @@ -# PatternFly Guidelines - -Core development rules for AI coders building PatternFly React applications. - -## Related Files - -- [**Component Rules**](./component-architecture.md) - Component structure requirements -- [**Styling Rules**](./styling-standards.md) - CSS and styling requirements -- [**Layout Rules**](../components/layout/README.md) - Page structure requirements - -## Essential Rules - -### Version Requirements - -- ✅ **ALWAYS use PatternFly v6** - Use `pf-v6-` prefixed classes only -- ❌ **NEVER use legacy versions** - No `pf-v5-`, `pf-v4-`, or `pf-c-` classes -- ✅ **Match component and CSS versions** - Ensure compatibility - -### Component Usage Rules - -- ✅ **Use PatternFly components first** - Before creating custom solutions -- ✅ **Compose components** - Build complex UIs by combining PatternFly components -- ❌ **Don't override component internals** - Use provided props and APIs - -### Tokenss -- ✅ **ALWAYS use PatternFly tokens** - Use `pf-t-` prefixed classes over `pf-v6-` classes (e.g., `var(--pf-t--global--spacer--sm)` not `var(--pf-v6-global--spacer--sm)`) - -### Text Components (v6+) -```jsx -// ✅ Correct -import { Content } from '@patternfly/react-core'; -Title - -// ❌ Wrong - Don't use old Text components -Title -``` - -### Icon Usage -```jsx -// ✅ Correct - Wrap with Icon component -import { Icon } from '@patternfly/react-core'; -import { UserIcon } from '@patternfly/react-icons'; - -``` - -### Styling Rules - -- ✅ **Use PatternFly utilities** - Before writing custom CSS -- ✅ **Use semantic design tokens** for custom CSS (e.g., `var(--pf-t--global--text--color--regular)`), not base tokens with numbers (e.g., `--pf-t--global--text--color--100`) or hardcoded values -- ❌ **Don't mix PatternFly versions** - Stick to v6 throughout - -### Documentation Requirements - -1. **Check [PatternFly.org](https://www.patternfly.org/) first** - Primary source for APIs -2. **Check the [PatternFly React GitHub repository](https://github.com/patternfly/patternfly-react)** for the latest source code, examples, and release notes -3. **Use "View Code" sections** - Copy working examples -4. **Reference version-specific docs** - Match your project's PatternFly version -5. **Provide context to AI** - Share links and code snippets when asking for help - -> For the most up-to-date documentation, use both the official docs and the source repositories. When using AI tools, encourage them to leverage context7 to fetch the latest documentation from these sources. - -### Accessibility Requirements - -- ✅ **WCAG 2.1 AA compliance** - All components must meet standards -- ✅ **Proper ARIA labels** - Use semantic markup and labels -- ✅ **Keyboard navigation** - Ensure full keyboard accessibility -- ✅ **Focus management** - Logical focus order and visible indicators - -## Quality Checklist - -- [ ] Uses PatternFly v6 classes only -- [ ] Components render correctly across browsers -- [ ] Responsive on mobile and desktop -- [ ] Keyboard navigation works -- [ ] Screen readers can access content -- [ ] No console errors or warnings -- [ ] Performance is acceptable - -## When Issues Occur - -1. **Check [PatternFly.org](https://www.patternfly.org/)** - Verify component API -2. **Inspect elements** - Use browser dev tools for PatternFly classes -3. **Search [GitHub issues](https://github.com/patternfly/patternfly-react/issues)** - Look for similar problems -4. **Provide context** - Share code snippets and error messages - -See [Common Issues](../troubleshooting/common-issues.md) for specific problems. \ No newline at end of file diff --git a/documentation/guidelines/ai-prompt-guidance.md b/documentation/guidelines/ai-prompt-guidance.md deleted file mode 100644 index fce88e1d..00000000 --- a/documentation/guidelines/ai-prompt-guidance.md +++ /dev/null @@ -1,146 +0,0 @@ -# AI Prompt Guidance for PatternFly Development - -Guidelines for creating effective prompts when using AI coding assistants with PatternFly React applications. - -## Why Specific Prompts Matter - -Based on workshop feedback, AI coding assistants work best with PatternFly when given specific, detailed prompts. Vague prompts often result in: -- Non-existent component usage → See [Common Issues](../troubleshooting/common-issues.md#ai-coding-specific-issues) -- Incorrect styling approaches → See [Styling Standards](./styling-standards.md) -- Missing accessibility features → See [Guidelines](./README.md#accessibility-requirements) - -## Essential Prompt Template - -``` -Create a [FEATURE] using PatternFly v6 React components. Requirements: -- Follow PatternFly component composition patterns (see styling-standards.md) -- Use component props for spacing/layout before considering utility classes -- Ensure keyboard accessibility with proper ARIA labels -- Verify all components exist in PatternFly packages before using -- [SPECIFIC_FEATURE_REQUIREMENTS] -- Reference: [LINK_TO_RELEVANT_DOCS] -``` - -## Prompt Strategy by Use Case - -### Dashboard/Data Pages -**Key prompt additions:** -``` -- Use proper component hierarchy: PageSection > Stack > Grid > Card -- For tabular data, use PatternFly Table component (see data-display/table.md) -- For charts, follow charts/README.md import requirements (/victory path) -``` - -### Forms -**Key prompt additions:** -``` -- Follow form structure: PageSection > Form > FormGroup > ActionGroup -- Use ActionGroup component for button spacing (see styling-standards.md) -``` - -### Navigation/Layout -**Key prompt additions:** -``` -- Use existing AppLayout structure in src/app/AppLayout/ -- Follow routing patterns in src/app/routes.tsx -- Reference layout/README.md for proper component usage -``` - -### Charts Integration -**Key prompt additions:** -``` -- CRITICAL: Import from @patternfly/react-charts/victory (see charts/README.md) -- Follow chart color guidance in charts/README.md -``` - -### Chatbot Integration -**Key prompt additions:** -``` -- Follow dynamic import patterns from chatbot/README.md -- Reference official PatternFly chatbot demos (links in chatbot/README.md) -``` - -## Error Prevention Strategies - -### Component Existence -**Prompt addition:** -``` -"Before using any component, verify it exists by checking: -- Core components: @patternfly/react-core documentation -- Tables: @patternfly/react-table documentation -- Charts: @patternfly/react-charts documentation -See troubleshooting/common-issues.md for common non-existent components to avoid." -``` - -### Styling Approach -**Prompt addition:** -``` -"Follow the component-first approach from styling-standards.md: -1. Use proper component composition first -2. Use component props second -3. Use utility classes only as last resort -Do NOT use CSS modules syntax (className={styles.*}) - this project doesn't support them." -``` - -### Import Paths -**Prompt addition:** -``` -"Use correct import paths as documented in: -- Charts: charts/README.md (must include /victory) -- Chatbot: chatbot/README.md (dynamic imports) -- Core: standard @patternfly/react-core imports" -``` - -## Deployment Prompting - -**When requesting deployment guidance:** -``` -"After creating the prototype, provide deployment instructions following deployment-guide.md. -Include build command and choose appropriate service (Surge for quick sharing, Vercel for professional demos)." -``` - -## Complete Example Prompt - -``` -Create a user management page using PatternFly v6 with these requirements: - -Component Structure: -- Follow component hierarchy from styling-standards.md: PageSection > Stack > Toolbar + Table -- Use Table component with proper props (borders, gridBreakPoint) - see data-display/table.md -- Use ActionGroup for buttons (provides spacing automatically) - -Technical Requirements: -- Verify all components exist in PatternFly packages before using -- Follow accessibility guidelines from guidelines/README.md -- Handle loading/error/empty states as shown in troubleshooting/common-issues.md - -Project Integration: -- Follow existing routing patterns in src/app/routes.tsx -- Integrate with existing AppLayout structure -- Match patterns from existing pages in src/app/ - -References: -- Component patterns: styling-standards.md -- Table specifics: data-display/table.md -- Accessibility: guidelines/README.md -- Error handling: troubleshooting/common-issues.md -``` - -## Quick Reference for Prompts - -- **Component composition patterns**: [styling-standards.md](./styling-standards.md) -- **Table usage**: [data-display/table.md](../components/data-display/table.md) -- **Chart requirements**: [charts/README.md](../charts/README.md) -- **Chatbot implementation**: [chatbot/README.md](../chatbot/README.md) -- **Common errors to avoid**: [common-issues.md](../troubleshooting/common-issues.md) -- **Deployment options**: [deployment-guide.md](./deployment-guide.md) - -## Best Practices Summary - -1. **Reference documentation** - Include links to relevant .md files in your prompts -2. **Be specific about structure** - Mention component hierarchy requirements -3. **Prevent common errors** - Reference troubleshooting guide proactively -4. **Verify existence** - Ask AI to confirm components exist before using -5. **Include context** - Reference existing project files when applicable - -The key is combining specific prompting with references to the detailed guidance already documented in this project's other files. \ No newline at end of file diff --git a/documentation/guidelines/component-architecture.md b/documentation/guidelines/component-architecture.md deleted file mode 100644 index 2ffe0579..00000000 --- a/documentation/guidelines/component-architecture.md +++ /dev/null @@ -1,92 +0,0 @@ -# Component Architecture - -This document outlines the essential rules for structuring PatternFly components, managing state, and ensuring performance. It is a high-level guide that links to more detailed documentation for specific patterns. - -## Related Files -- [**Layout Rules**](../components/layout/README.md) - For page structure and layout patterns. -- [**Table Component Rules**](../components/data-display/table.md) - For table usage, selection, and actions. -- [**Data View Component Rules**](../components/data-display/README.md) - For data view usage. -- [**Styling Rules**](./styling-standards.md) - For CSS and styling approaches. - -## 1. Component Composition - -### PatternFly-First Approach -Always start with standard PatternFly components and compose them to build complex UIs. Avoid creating custom components when a PatternFly solution already exists. - -```jsx -// ✅ Correct: Compose existing PatternFly components -import { Card, CardTitle, CardBody, Button, Content } from '@patternfly/react-core'; - -const UserCard = ({ user, onEdit }) => ( - - {user.name} - - {user.email} - - - -); -``` - -### Component Hierarchy -Structure your application in a clear hierarchy: -1. **Page Components**: Top-level page structure. -2. **Section Components**: Major page sections, often corresponding to a `PageSection`. -3. **Feature Components**: Components that encapsulate a specific piece of functionality. -4. **PatternFly Components**: The base building blocks from `@patternfly/react-core`. - -### Data Display -For displaying labeled data or key-value pairs, always use PatternFly's `DescriptionList` components for clarity and accessibility. -- **See**: [DescriptionList Documentation](https://www.patternfly.org/components/description-list) - -## 2. State Management - -### Local vs. Shared State -- **Local State (`useState`)**: Use for component-specific UI state like form inputs or toggles. -- **Shared State (`useContext`)**: Use for state that needs to be accessed by multiple components in a tree. -- **Complex State (`useReducer`)**: Use for state with complex update logic. - -Keep state as local as possible and only lift it when necessary. - -## 3. Common Patterns - -For detailed guidance and code examples on common UI patterns, refer to the specific documentation: - -- **Selectable Tables**: See [Table Component Rules](../components/data-display/table.md). -- **Dropdown Actions**: See the [Dropdown Documentation](https://www.patternfly.org/components/menus/dropdown). -- **Toolbar with Filters**: See the [Toolbar Documentation](https://www.patternfly.org/components/toolbar). - -## 4. Error Handling and Data States - -Always account for different data states in your components: -- ✅ **Loading State**: Show a `Spinner` or `Skeleton` while data is fetching. -- ✅ **Error State**: Display a clear error message, often using `EmptyState`. -- ✅ **Empty State**: Provide a message when there is no data to display. - -```jsx -// ✅ Required: Handle all data states -import { EmptyState, Spinner } from '@patternfly/react-core'; - -if (isLoading) return ; -if (error) return ; -if (!data?.length) return ; - -return ; -``` - -## 5. Performance - -- **Memoization**: Use `React.memo`, `useCallback`, and `useMemo` to prevent unnecessary re-renders, especially in lists. -- **Virtualization**: For long lists or tables (1000+ rows), use a virtualization library to ensure performance. -- **Lazy Loading**: Use `React.lazy` and `Suspense` to code-split parts of your application and load them on demand. - -## 6. Testing - -- **Focus on Behavior**: Test what the user can do (e.g., clicking a button, filling a form), not component implementation details. -- **Accessibility**: Always include tests for ARIA attributes and keyboard navigation. -- **Don't Test PatternFly**: Trust that PatternFly components are already tested. Focus your tests on your application's logic. - -## Quick Reference -- [**PatternFly Components**](https://www.patternfly.org/components) - Official component documentation -- [**React Patterns**](https://reactpatterns.com/) - Common React patterns and best practices -- [**Testing Library**](https://testing-library.com/) - Component testing best practices diff --git a/documentation/guidelines/deployment-guide.md b/documentation/guidelines/deployment-guide.md deleted file mode 100644 index 8be82b19..00000000 --- a/documentation/guidelines/deployment-guide.md +++ /dev/null @@ -1,242 +0,0 @@ -# Quick Deployment Guide for Prototypes - -This guide provides simple, fast methods for building and deploying your React application so you can share a live prototype with others. - -## Introduction - -Once you have a working prototype on your local machine, the next step is to host it on a public URL. The services listed below are excellent for this purpose, offering generous free tiers and simple command-line interfaces (CLIs) that make deployment a breeze. - -## 1. Build Your Application - -Before you can deploy, you need to create a production-ready build of your application. This process compiles your React code into a set of static HTML, CSS, and JavaScript files that can be served by any web server. - -From your project's root directory, run the following command: - -```bash -# Using npm -npm run build - -# Or using yarn -yarn build -``` - -This command will create a new directory named `dist` (or sometimes `build`) in your project. This is the folder you will deploy. - -## 2. Choose a Deployment Service - -Here are four popular options for hosting your static site, ranked from simplest to most involved. For the absolute fastest deployment with no prior setup, Surge is the best choice. - -### ⚡ Quick Comparison - -| Service | Speed | Setup Required | Custom Domains | Notes | -|---------|-------|----------------|----------------|--------| -| **Surge** | Fastest | None | Yes (paid) | Best for instant sharing | -| **Vercel** | Fast | Account signup | Yes (free) | Best overall experience | -| **Netlify** | Fast | Account signup | Yes (free) | Good alternative to Vercel | -| **GitHub Pages** | Slower | Git repo required | Yes (free) | Best if already using GitHub | - -### 🎯 Recommendation by Use Case - -- **Quick prototype sharing**: Use Surge -- **Professional demo**: Use Vercel or Netlify -- **Open source project**: Use GitHub Pages - -### Option A: Deploying with Surge - -Surge is famous for its simplicity and speed, making it an excellent choice for instant deployments. You can create an account directly from the command line on your first use. - -1. **Install the Surge CLI**: - ```bash - npm install -g surge - ``` - -2. **Deploy your app**: - From your project's root directory, run the `surge` command and point it to your build folder. - ```bash - surge dist - ``` - The first time you use it, Surge will prompt you to create a free account. It will then ask you to confirm the publish directory and will suggest a random domain name, which you can edit on the fly before deploying. - - Your site will be live moments after you hit Enter. - -### Option B: Deploying with Vercel - -Vercel is a zero-configuration deployment platform that is also incredibly easy to use. - -1. **Install the Vercel CLI**: - ```bash - npm install -g vercel - ``` - -2. **Log in to your Vercel account**: - ```bash - vercel login - ``` - *(This will open a browser window for you to log in or sign up.)* - -3. **Deploy your app**: - From your project's root directory, run the `vercel` command. - ```bash - vercel - ``` - Vercel's CLI will guide you through a few simple questions. In most cases, you can accept the default answers. It will automatically detect that you have a Vite-based React app and deploy the `dist` directory. - - Once finished, it will give you a public URL for your prototype. - -### Option C: Deploying with Netlify - -Netlify is another excellent platform for deploying static sites, with a very similar workflow to Vercel. - -1. **Install the Netlify CLI**: - ```bash - npm install -g netlify-cli - ``` - -2. **Log in to your Netlify account**: - ```bash - netlify login - ``` - -3. **Deploy your app**: - From your project's root directory, run the `netlify deploy` command. - ```bash - netlify deploy --prod - ``` - The CLI will ask you for the "Publish directory". Enter `dist` (or the name of your build output folder). It will then deploy your site and provide you with a live URL. - -### Option D: Deploying with GitHub Pages - -If your project is already a GitHub repository, GitHub Pages is a convenient, free option, though it requires more setup than the other services. - -1. **Install the `gh-pages` package**: - ```bash - npm install --save-dev gh-pages - ``` - -2. **Update your `package.json`**: - Add a `homepage` field and a `deploy` script. The `homepage` URL should follow this format: `https://.github.io/`. - - ```json - { - "name": "my-react-app", - "homepage": "https://my-username.github.io/my-react-app", - "scripts": { - "dev": "vite", - "build": "vite build", - "deploy": "gh-pages -d dist", - "preview": "vite preview" - }, - // ... other package.json contents - } - ``` - -3. **Deploy**: - First, build your application, then run the new `deploy` script. - ```bash - # 1. Build the app - npm run build - - # 2. Deploy to GitHub Pages - npm run deploy - ``` - This will create a new `gh-pages` branch in your repository and publish the contents of your `dist` folder to it. After a minute or two, your prototype will be live at the URL you specified in the `homepage` field. - -## Troubleshooting Common Deployment Issues - -### Surge Issues - -**Problem**: `surge` command not found -```bash -# Solution: Install globally -npm install -g surge -``` - -**Problem**: Permission denied or login issues -```bash -# Solution: Clear surge cache and login again -surge logout -surge login -``` - -**Problem**: Domain name conflicts -```bash -# Solution: Use a different domain name -surge dist --domain my-unique-project-name.surge.sh -``` - -### Vercel Issues - -**Problem**: Build fails on Vercel -```bash -# Solution: Check that your build command is correct -# In package.json, verify: -"scripts": { - "build": "webpack --mode production" -} -``` - -**Problem**: Vercel login issues -```bash -# Solution: Use email-based login instead of GitHub -vercel login --email your-email@example.com -``` - -### Netlify Issues - -**Problem**: Build directory not found -```bash -# Solution: Ensure you're pointing to the correct build directory -netlify deploy --dir dist --prod -``` - -**Problem**: Environment variables needed -```bash -# Solution: Set environment variables in Netlify dashboard -# Or use .env file for local builds -``` - -### General Build Issues - -**Problem**: Build fails with module errors -```bash -# Solution: Clean install and build -rm -rf node_modules package-lock.json -npm install -npm run build -``` - -**Problem**: React Router paths not working after deployment -```bash -# Solution: Most services need redirects configured -# For Surge, create a file called CNAME in your dist folder -# For Vercel/Netlify, they handle this automatically -``` - -## Sharing Your Prototype - -Once deployed, you can share your prototype URL with others. Consider: - -1. **Add a README** with deployment instructions -2. **Test on different devices** to ensure responsiveness -3. **Share the source code** if it's meant to be a reference -4. **Document any special setup** needed for local development - -## Quick Deployment Commands Reference - -```bash -# Surge (fastest) -npm run build -surge dist - -# Vercel -npm run build -vercel - -# Netlify -npm run build -netlify deploy --prod - -# GitHub Pages -npm run build -npm run deploy -``` \ No newline at end of file diff --git a/documentation/guidelines/styling-standards.md b/documentation/guidelines/styling-standards.md deleted file mode 100644 index 3c4a2005..00000000 --- a/documentation/guidelines/styling-standards.md +++ /dev/null @@ -1,419 +0,0 @@ -# Styling Standards - -Essential CSS and styling rules for PatternFly React applications. - -## Related Files -- [**PatternFly Guidelines**](./README.md) - Core development principles -- [**Component Rules**](./component-architecture.md) - Component structure patterns -- [**Layout Rules**](../components/layout/README.md) - Page layout styling - -## Class Naming Rules - -### PatternFly v6 Requirements -- ✅ **ALWAYS use `pf-v6-` prefix** - All PatternFly v6 classes -- ❌ **NEVER use legacy prefixes** - No `pf-v5-`, `pf-v4-`, `pf-u` or `pf-c-` - -```css -/* ✅ Correct v6 classes */ -.pf-v6-c-button /* Components */ -.pf-v6-u-m-md /* Utilities */ -.pf-v6-l-grid /* Layouts */ - -/* ❌ Wrong - Don't use these */ -.pf-v5-c-button -.pf-u-m-md -.pf-c-button -``` - -## Component Composition Rules - -> **Component-first approach:** Use proper PatternFly component composition for layout and spacing. Components should be children of appropriate containers like PageSection, ActionGroup, Stack, etc. - -### Use Component Composition First -```jsx -// ✅ Correct - Use proper component composition - - - Dashboard - Dashboard content - - - -// ❌ Wrong - Utility classes for basic layout -
-
Dashboard
-
Dashboard content
-
-``` - -### Use Component Props Second -```jsx -// ✅ Correct - Use component props for spacing and layout - - - - - - -
Name
- - - - - - -// ❌ Wrong - Utility classes when component props exist - - - -
-``` - -### Common Component Patterns for Layout -```jsx -// Page structure - - - Page Title - - - - Card Title - Card content - - - - - - -// Form structure -
- - - - - - -
-``` - -### When to Use Utility Classes -Use utility classes only when: -- Component composition doesn't provide the needed layout -- Component props don't offer the required styling -- You need to override specific styling for edge cases - -```jsx -// ✅ Acceptable utility usage - when component props aren't sufficient - {/* Force card to full height */} - - {/* Center text when component doesn't provide prop */} - Centered content - - - -``` - -## Design Token Rules - -### Use Semantic PatternFly Tokens for Custom CSS -- ✅ **Use semantic tokens** (e.g., `--pf-t--global--text--color--regular`) for custom CSS. These tokens do not end in numbers and are intended for application-level styling. -- ❌ **Don't use base tokens** (which end in numbers, e.g., `--pf-t--global--text--color--100`) for custom CSS. Base tokens are for internal PatternFly use and may change. - -```css -.custom-component { - /* ✅ Correct - Use semantic tokens */ - color: var(--pf-t--global--text--color--regular); - margin: var(--pf-t-global--spacer--md); - - /* ❌ Wrong - Hardcoded values or base tokens */ - /* color: #333333; */ - /* color: var`--pf-t--global--text--color--100); */ - /* margin: 16px; */ -} -``` - -### Essential Token Categories -```css -/* Semantic Colors */ ---pf-t--global--text--color--regular ---pf-t--global--text--color--subtle ---pf-t--global--background--color--primary--default - -/* Spacing */ ---pf-t-global--spacer--{xs|sm|md|lg|xl} - -/* Typography */ ---pf-t--global--font--family--body ---pf-t--global--font--size--md -``` - -## Responsive Design Rules - -### Use PatternFly Responsive Utilities -```css -/* Mobile-first responsive patterns */ -.pf-v6-u-display-none-on-sm /* Hide on small screens */ -.pf-v6-u-display-block-on-md /* Show on medium+ */ -.pf-v6-u-text-align-center-on-lg /* Center on large+ */ -``` - -### Grid Layout Patterns -```jsx -
-
- Responsive content -
-
-``` - -## Component Styling Rules - -> **No emojis or raw icons:** Always use PatternFly's React icon components (from `@patternfly/react-icons`) for all icons, including status, trend, and navigation icons. -> -> **No direct HTML headings or paragraphs:** Use PatternFly's `Title` for headings and `Content` with `component="p"` for paragraphs. - -### Button Styling -```jsx -// ✅ Use PatternFly variants and ActionGroup for spacing - - - - - -// ❌ Wrong - Utility classes for button spacing -
- - -
-``` - -### Form Styling -```jsx -// ✅ Use PageSection and proper form structure - -
- - - - - - -
- - -// ❌ Wrong - Utility classes for form layout -
- - - -
-``` - -## Performance Rules - -### CSS Efficiency -- ✅ **Use single utility classes** - More efficient than custom CSS -- ✅ **Import only needed CSS** - Tree shake unused styles -- ❌ **Don't create custom classes** - When PatternFly utilities exist - -## Troubleshooting Rules - -### Common Issues -1. **Missing styles** - Ensure PatternFly CSS is imported -2. **Class conflicts** - PatternFly classes should not be overridden -3. **Version mismatches** - All PatternFly packages must use same version - -### Debug Tools -- **Browser DevTools** - Inspect applied PatternFly classes -- **PatternFly DevTools** - Browser extension for debugging - -## Utility Class Usage Guidance - -> **Caution:** Avoid over-relying on utility classes to style components. Prefer using the component's own props and API for layout and appearance, as these are designed for recommended use cases. Use utility classes only when necessary, and add a comment explaining why the utility class is required. This approach helps ensure your code remains maintainable and aligned with future PatternFly updates. - -## Essential Do's and Don'ts - -### ✅ Do's -- Use proper PatternFly component composition (PageSection, Stack, Grid, ActionGroup) -- Leverage component props for spacing, borders, and layout (Table borders, ActionGroup spacing) -- Use PatternFly v6 components and design patterns exclusively -- Use utility classes only as a last resort when composition and props aren't sufficient -- Use PatternFly design tokens for any custom styles -- Test responsive behavior on different screen sizes - -### ❌ Don'ts -- Use utility classes for basic layout when proper component composition exists -- Skip using component props in favor of utility classes -- Mix PatternFly versions -- Override PatternFly component internals -- Use hardcoded values instead of design tokens -- Create custom layout when PatternFly layout components exist - -## Quick Reference -- **[PatternFly Utilities](https://www.patternfly.org/utilities)** - Complete utility documentation -- **[Design Tokens](https://www.patternfly.org/tokens)** - Available design tokens -- **[Responsive Design](https://www.patternfly.org/layouts)** - Layout and responsive patterns - -## Do/Don't Examples - -### Proper Layout and Spacing -**Do:** -```jsx -// Use proper component composition - - - Content Title - Content goes here - - -``` -**Don't:** -```jsx -// Avoid inline styles or utility classes for basic layout -
Content
-
Content
-``` - -### Use Component Props for Spacing -**Do:** -```jsx -// Use component props when available - - - - - - -
Name
-``` -**Don't:** -```jsx -// Don't use utility classes when component props exist - - - - - - -
Name
-``` - -### No Emojis or Raw Icons -**Do:** -```jsx -import ArrowUpIcon from '@patternfly/react-icons/dist/esm/icons/arrow-up-icon'; - -``` -**Don't:** -```jsx -📈 -``` - -### No Direct HTML Headings or Paragraphs -**Do:** -```jsx -import { Title, Content } from '@patternfly/react-core'; -Dashboard -This is a PatternFly app. -``` -**Don't:** -```jsx -

Dashboard

-

This is a PatternFly app.

-``` - ---- - -> **Note:** `PageHeader` is not a PatternFly component in v6+. Use `PageSection`, `Title`, and layout components instead. - -## Spacing and Inline Styles - -- ✅ **Always use PatternFly spacing variables (design tokens) for all spacing, including in inline style props.** -- ❌ **Do not use hardcoded numbers for margin, padding, or other spacing in inline styles.** - -**Correct:** -```jsx -
-``` - -**Incorrect:** -```jsx -
-``` - -## Utility Classes vs Inline Styles - -- ✅ **Prefer using PatternFly utility classes for spacing, alignment, and layout instead of inline styles.** -- ❌ **Only use inline styles if a PatternFly utility class does not exist for the required spacing or layout.** - -**Correct:** -```jsx -
-``` - -**Incorrect:** -```jsx -
-``` - -## External Link Buttons - -- ✅ **Always add an external link icon to the right of the text for external link buttons.** -- ❌ **Do not omit the external link icon for buttons that open external sites.** - -**Correct:** -```jsx -import { ExternalLinkAltIcon } from '@patternfly/react-icons'; - -``` - -**Incorrect:** -```jsx - -``` - -## Toolbar Alignment - -- ✅ **When right-aligning content in a PatternFly Toolbar, use the ToolbarItem align={{ default: 'alignEnd' }} prop.** -- ❌ **Do not use custom Flex wrappers or utility classes to right-align Toolbar content.** - -**Correct:** -```jsx - - - Left content - Right-aligned content - - -``` - -**Incorrect:** -```jsx - - - Left content - - Right-aligned content - - - -``` \ No newline at end of file diff --git a/documentation/resources/README.md b/documentation/resources/README.md deleted file mode 100644 index cd36898c..00000000 --- a/documentation/resources/README.md +++ /dev/null @@ -1,37 +0,0 @@ -# PatternFly Resources - -This directory contains essential resources for PatternFly development, including external links and local documentation references. - -## Available Resources - -- **[External Links](./external-links.md)** - Comprehensive list of official PatternFly documentation, repositories, and community resources -- **[Local Files](./local-files.md)** - Project-specific documentation files and context - -## Quick Access - -### Most Important Resources -- [PatternFly Components](https://www.patternfly.org/components) - Complete component library -- [PatternFly React Repository](https://github.com/patternfly/patternfly-react) - Source code and examples -- [PatternFly Design Guidelines](https://www.patternfly.org/get-started/design) - Design principles - -### Development Resources -- [PatternFly React Seed](https://github.com/patternfly/patternfly-react-seed) - Starter template -- [Charts Documentation](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts#readme) - Data visualization -- [Chatbot Components](https://www.patternfly.org/patternfly-ai/chatbot/overview) - AI chatbot patterns - -## Related Documentation - -- **[Setup Guide](../setup/README.md)** - Project initialization and environment setup -- **[Guidelines](../guidelines/README.md)** - Core development principles -- **[Troubleshooting](../troubleshooting/common-issues.md)** - Common issues and solutions - -## Usage - -When working with AI assistants or seeking help with PatternFly development: - -1. **Start with External Links**: Check the comprehensive resource list in `external-links.md` -2. **Reference Local Context**: Use `local-files.md` for project-specific patterns -3. **Provide Specific Links**: Share relevant documentation URLs when asking for help -4. **Include Code Examples**: Reference working examples from the PatternFly repositories - -This resource directory ensures you have quick access to the most important PatternFly development resources and can effectively communicate your needs to AI assistants and community members. diff --git a/documentation/resources/external-links.md b/documentation/resources/external-links.md deleted file mode 100644 index 1b82a8ba..00000000 --- a/documentation/resources/external-links.md +++ /dev/null @@ -1,229 +0,0 @@ -# External References - -This document provides links to official PatternFly documentation, repositories, and helpful external resources for AI coders working with PatternFly React applications. - -## Introduction - -External resources are essential for staying current with PatternFly updates, finding implementation examples, and troubleshooting issues. This curated list provides direct access to the most important PatternFly resources and community support channels. - -## Related Files - -- [**PatternFly Guidelines**](../guidelines/README.md) - Core development principles. -- [**Setup Guide**](../setup/README.md) - Initial project setup resources -- [**Troubleshooting**](../troubleshooting/common-issues.md) - Problem-solving resources - -## Official PatternFly Documentation - -### Primary Documentation -- **[PatternFly.org](https://www.patternfly.org/)** - Main documentation site with component APIs and examples -- **[PatternFly Design Guidelines](https://www.patternfly.org/get-started/design)** - Design principles and patterns -- **[PatternFly React Components](https://www.patternfly.org/components)** - Complete component library documentation -- **[PatternFly Layouts](https://www.patternfly.org/layouts)** - Layout system and grid documentation - -### Component-Specific Documentation -- **[Button Component](https://www.patternfly.org/components/button)** - Button variants and usage -- **[Table Component](https://www.patternfly.org/components/table)** - Composable table implementation -- **[Dropdown Component](https://www.patternfly.org/components/menus/dropdown)** - Dropdown and menu patterns -- **[Toolbar Component](https://www.patternfly.org/components/toolbar)** - Toolbar with filters and actions -- **[Page Component](https://www.patternfly.org/components/page)** - Page layout and structure -- **[Icon Component](https://www.patternfly.org/components/icon)** - Icon usage and sizing - -### Utility Classes Documentation -- **[Accessibility](https://www.patternfly.org/utility-classes/accessibility)** - Accessibilty utility classes -- **[Alignment](https://www.patternfly.org/utility-classes/alignment)** - Alignment utility classes -- **[Background color](https://www.patternfly.org/utility-classes/background-color)** - Background utility classes -- **[Box shadow](https://www.patternfly.org/utility-classes/box-shadow)** - Box shadow utility classes -- **[Display](https://www.patternfly.org/utility-classes/display)** - Display utility classes -- **[Flex](https://www.patternfly.org/utility-classes/flex)** - Flex utility classes -- **[Float](https://www.patternfly.org/utility-classes/float)** - Float utility classes -- **[Sizing](https://www.patternfly.org/utility-classes/sizing)** - Sizing utility classes -- **[Spacing](https://www.patternfly.org/utility-classes/spacing)** - Spacing utility classes -- **[Text](https://www.patternfly.org/utility-classes/text)** - Text utility classes - - -### Specialized Features -- **[PatternFly Charts](https://www.patternfly.org/charts/about)** - Data visualization guidelines -- **[PatternFly AI - Chatbot](https://www.patternfly.org/patternfly-ai/chatbot/overview)** - AI chatbot components -- **[Accessibility Guidelines](https://www.patternfly.org/accessibility/accessibility-fundamentals)** - WCAG compliance and best practices - -## Official Repositories - -### Core Repositories -- **[PatternFly React](https://github.com/patternfly/patternfly-react)** - Main React component library -- **[PatternFly Core](https://github.com/patternfly/patternfly)** - HTML/CSS foundation -- **[PatternFly React Seed](https://github.com/patternfly/patternfly-react-seed)** - Starter template for new projects - -### Specialized Packages -- **[PatternFly Charts Repository](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts)** - Charts package source and examples -- **[PatternFly Icons](https://github.com/patternfly/patternfly-react/tree/main/packages/react-icons)** - Icon library source -- **[PatternFly Tokens](https://github.com/patternfly/patternfly-react/tree/main/packages/react-tokens)** - Design tokens package - -### Example Applications -- **[PatternFly Demo App](https://github.com/patternfly/patternfly-react-demo-app)** - Complete demo application -- **[PatternFly Quickstarts](https://github.com/patternfly/patternfly-quickstarts)** - Interactive tutorials and guides - -## Component Examples and Code Snippets - -### "View Code" Sections -Most PatternFly component pages include "View Code" sections that provide working examples: -- Navigate to any component page on [patternfly.org](https://www.patternfly.org/) -- Look for the "View Code" button or link -- Copy and adapt the provided code snippets -- Use these as starting points for your implementations - -### Repository Examples -Find practical examples in the PatternFly repositories: -- **Component Examples**: `patternfly-react/packages/react-core/src/components/[ComponentName]/examples/` -- **Demo Files**: `*.tsx` and `*.jsx` files in component directories -- **Test Files**: Component test files often contain usage examples - -### Useful Repository Paths -``` -patternfly-react/ -├── packages/react-core/src/components/ -│ ├── Button/examples/ -│ ├── Table/examples/ -│ ├── Dropdown/examples/ -│ └── [ComponentName]/examples/ -├── packages/react-table/src/components/ -└── packages/react-charts/src/components/ -``` - -## Charts and Visualization Resources - -### PatternFly Charts -- **[Charts README](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts#readme)** - Installation and usage guide -- **[Victory.js Documentation](https://formidable.com/open-source/victory/)** - Underlying charting library -- **[ECharts Documentation](https://echarts.apache.org/)** - Alternative charting library - -### Chart Examples -- **[Chart Component Examples](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts/src/components)** - Source code examples -- **[PatternFly Chart Demos](https://www.patternfly.org/charts)** - Interactive chart examples - -## Chatbot Resources - -### PatternFly Chatbot -- **[Chatbot Overview](https://www.patternfly.org/patternfly-ai/chatbot/overview)** - Main chatbot documentation -- **[Basic Chatbot Demo](https://www.patternfly.org/patternfly-ai/chatbot/overview/demo/basic-chatbot)** - Simple chatbot implementation -- **[Embedded Chatbot Demo](https://www.patternfly.org/patternfly-ai/chatbot/overview/demo/embedded-chatbot)** - Embedded chatbot pattern -- **[Chatbot Demos Overview](https://www.patternfly.org/patternfly-ai/chatbot/overview/demo)** - All chatbot demo variations - -### Implementation Resources -- **Demo Source Code**: Available on each demo page via "View Code" sections -- **Component API**: Detailed props and usage information -- **Integration Examples**: How to integrate with existing PatternFly applications - -## Community and Support - -### GitHub Resources -- **[Issues](https://github.com/patternfly/patternfly-react/issues)** - Bug reports and feature requests -- **[Discussions](https://github.com/patternfly/patternfly-react/discussions)** - Community Q&A and discussions -- **[Pull Requests](https://github.com/patternfly/patternfly-react/pulls)** - Code contributions and reviews - -### Communication Channels -- **[PatternFly Slack](https://patternfly.slack.com/)** - Real-time community support -- **[PatternFly Forum](https://forum.patternfly.org/)** - Long-form discussions and help -- **[Stack Overflow](https://stackoverflow.com/questions/tagged/patternfly)** - Technical Q&A with `patternfly` tag - -## Development Tools and Extensions - -### Browser Extensions -- **[React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/)** - React component debugging -- **[PatternFly DevTools](https://github.com/patternfly/patternfly-devtools)** - PatternFly-specific debugging tools - -### IDE Extensions -- **[VS Code PatternFly Snippets](https://marketplace.visualstudio.com/search?term=patternfly)** - Code snippets for VS Code -- **[ES7+ React/Redux/React-Native snippets](https://marketplace.visualstudio.com/items?itemName=dsznajder.es7-react-js-snippets)** - React development shortcuts - -## Learning Resources - -### Tutorials and Guides -- **[Getting Started Guide](https://www.patternfly.org/get-started/develop)** - Development setup and first steps -- **[Migration Guides](https://www.patternfly.org/get-started/upgrade)** - Upgrading between PatternFly versions -- **[Design System Principles](https://www.patternfly.org/get-started/design)** - Understanding PatternFly design philosophy - -### Video Resources -- **[PatternFly YouTube Channel](https://www.youtube.com/c/PatternFly)** - Tutorials and presentations -- **[Red Hat Developer](https://www.youtube.com/c/RedHatDeveloper)** - Related development content - -## Version-Specific Resources - -### PatternFly v6 (Current) -- **[v6 Documentation](https://www.patternfly.org/)** - Current version documentation -- **[v6 Migration Guide](https://www.patternfly.org/get-started/upgrade)** - Upgrading from v5 to v6 -- **[v6 Release Notes](https://github.com/patternfly/patternfly-react/releases)** - Latest changes and updates - -### Legacy Versions -- **[v5 Documentation](https://v5.patternfly.org/)** - Previous version (for reference only) -- **[v4 Documentation](https://v4.patternfly.org/)** - Older version (for legacy projects) - -## API References - -### Node.js and npm -- **[Node.js Downloads](https://nodejs.org/)** - Official Node.js installation -- **[npm Documentation](https://docs.npmjs.com/)** - Package manager documentation -- **[nvm (Node Version Manager)](https://github.com/nvm-sh/nvm)** - Managing multiple Node.js versions - -### React Ecosystem -- **[React Documentation](https://react.dev/)** - Official React documentation -- **[React Router](https://reactrouter.com/)** - Client-side routing -- **[React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)** - Component testing - -## Accessibility Resources - -### WCAG Guidelines -- **[WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)** - Web accessibility standards -- **[ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)** - ARIA implementation patterns -- **[WebAIM](https://webaim.org/)** - Accessibility evaluation and guidance - -### Testing Tools -- **[axe DevTools](https://www.deque.com/axe/devtools/)** - Accessibility testing browser extension -- **[WAVE](https://wave.webaim.org/)** - Web accessibility evaluation tool -- **[Lighthouse](https://developers.google.com/web/tools/lighthouse)** - Performance and accessibility auditing - -## Performance Resources - -### Optimization Guides -- **[React Performance](https://react.dev/learn/render-and-commit)** - React rendering optimization -- **[Webpack Bundle Analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)** - Bundle size analysis -- **[Web Vitals](https://web.dev/vitals/)** - Core web performance metrics - -### Monitoring Tools -- **[React DevTools Profiler](https://react.dev/blog/2018/09/10/introducing-the-react-profiler)** - Component performance profiling -- **[Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools)** - Browser performance tools - -## Best Practices for Using External Resources - -### Documentation Strategy -1. **Start with Official Docs**: Always check [patternfly.org](https://www.patternfly.org/) first -2. **Use "View Code" Sections**: Copy working examples from component pages -3. **Check Repository Examples**: Look at `*.tsx`/`*.jsx` files in PatternFly repos -4. **Provide Context to AI**: Share links and code snippets when asking for help - -### Staying Current -1. **Follow Release Notes**: Monitor [GitHub releases](https://github.com/patternfly/patternfly-react/releases) -2. **Join Community Channels**: Participate in Slack or forum discussions -3. **Subscribe to Updates**: Watch PatternFly repositories for notifications -4. **Regular Documentation Review**: Periodically review component documentation for updates - -### Troubleshooting Approach -1. **Search Issues First**: Check GitHub issues for similar problems -2. **Consult Multiple Sources**: Cross-reference documentation with examples -3. **Test Incrementally**: Isolate problems with minimal examples -4. **Share Specific Context**: Provide version numbers and code snippets when seeking help - -## Quick Reference Links - -### Most Frequently Used -- [PatternFly Components](https://www.patternfly.org/components) -- [PatternFly React Repository](https://github.com/patternfly/patternfly-react) -- [PatternFly React Seed](https://github.com/patternfly/patternfly-react-seed) -- [Charts README](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts#readme) -- [Chatbot Overview](https://www.patternfly.org/patternfly-ai/chatbot/overview) - -### Emergency Resources -- [GitHub Issues](https://github.com/patternfly/patternfly-react/issues) -- [Stack Overflow PatternFly Tag](https://stackoverflow.com/questions/tagged/patternfly) -- [PatternFly Slack](https://patternfly.slack.com/) - -Remember: **Always consult the official PatternFly documentation for your project's specific package versions.** Providing AI assistants with working code snippets or links to versioned documentation is highly effective for getting accurate implementation guidance. \ No newline at end of file diff --git a/documentation/resources/local-files.md b/documentation/resources/local-files.md deleted file mode 100644 index f0b9f5cc..00000000 --- a/documentation/resources/local-files.md +++ /dev/null @@ -1,30 +0,0 @@ -# Local Documentation Resources - -This document describes the key project-specific documentation files available for PatternFly development. These files provide essential context that complements the official PatternFly documentation. - -## Related Files -- [**External References**](./external-links.md) - Links to official PatternFly documentation. -- [**Code Examples**](./code-examples.md) - Curated, reusable code snippets. -- [**PatternFly Guidelines**](../guidelines/README.md) - Core development principles. - -## Core Local Documentation Files - -The following files are located in the project root and provide critical, specialized context for development. When working with AI assistants, providing relevant sections from these files is crucial for getting accurate and project-specific guidance. - -### 1. `patternfly-chatbot.txt` - -- **Location**: `../../patternfly-chatbot.txt` -- **Purpose**: The primary context file for the PatternFly Chatbot architecture. It contains component hierarchy, implementation patterns, and best practices specific to chatbot development. -- **When to Use**: Use as the main reference when building, integrating, or troubleshooting any chatbot features. - -### 2. `patternfly-react-component-groups.txt` - -- **Location**: `../../patternfly-react-component-groups.txt` -- **Purpose**: A comprehensive reference for PatternFly React component groups and specialized libraries. It covers component classifications, dependencies, and advanced composition patterns. -- **When to Use**: Use this file to discover appropriate components for complex UIs, understand component relationships, and implement enterprise-level features. - -## How to Use These Files - -1. **Consult First**: Before implementing a complex feature, check these files for project-specific patterns. -2. **Provide Context to AI**: When asking for help, copy and paste the most relevant sections from these files into your prompt. This will give the AI the context it needs to provide accurate guidance. -3. **Stay Updated**: These files are living documents. Refer to them for the latest project standards. \ No newline at end of file diff --git a/documentation/setup/README.md b/documentation/setup/README.md deleted file mode 100644 index 24084b6f..00000000 --- a/documentation/setup/README.md +++ /dev/null @@ -1,81 +0,0 @@ -# Setup Guide - -This section covers the initial setup and configuration for PatternFly React development projects. - -## Introduction - -The setup process for PatternFly React applications involves several key steps including environment preparation, project initialization, and dependency management. This guide provides comprehensive instructions for AI coders to establish a proper development environment. - -## Related Files - -- [**Quick Start**](./quick-start.md) - Step-by-step project initialization -- [**Development Environment**](./development-environment.md) - Environment configuration and tools -- [**PatternFly Guidelines**](../guidelines/README.md) - Core development principles -- [**Troubleshooting Setup Issues**](../troubleshooting/common-issues.md#setup-issues) - Common setup problems - -## Prerequisites - -Before starting any PatternFly React project, ensure the following requirements are met: - -### Required Software - -#### Node.js & npm -- **Requirement**: Node.js and npm must be installed and available in PATH -- **Verification**: Run `node --version && npm --version` to confirm installation -- **Installation**: Download from [https://nodejs.org/](https://nodejs.org/) -- **AI Note**: AI can verify these commands and guide installation if needed - -#### Optional: Node Version Manager (nvm) -- **Purpose**: Manage multiple Node.js versions -- **Usage**: If using nvm, ensure it's loaded and the correct Node version is active -- **Verification**: Run `nvm use node` to activate the latest version -- **AI Note**: Check if nvm is being used before proceeding with npm commands - -### System Requirements - -- **Operating System**: Windows, macOS, or Linux -- **Memory**: Minimum 4GB RAM (8GB recommended for development) -- **Storage**: At least 1GB free space for dependencies -- **Network**: Internet connection for package downloads - -## Project Initialization Methods - -### Method 1: PatternFly React Seed (Recommended) - -The PatternFly React Seed provides a complete scaffolding solution with: -- Pre-configured layout components -- Routing setup -- Build and test tools -- Development server configuration - -**Repository**: [patternfly-react-seed](https://github.com/patternfly/patternfly-react-seed) - -### Method 2: Manual Setup - -For custom project structures or specific requirements, manual setup allows full control over: -- Package selection -- Build configuration -- Project structure -- Development workflow - -## Next Steps - -1. Follow the [Quick Start Guide](./quick-start.md) for immediate project setup -2. Configure your [Development Environment](./development-environment.md) -3. Review [PatternFly Guidelines](../guidelines/README.md) for coding standards -4. Explore [Component Documentation](../components/) for implementation guidance - -## Best Practices - -- Always verify Node.js and npm versions before starting -- Use the PatternFly React Seed for new projects unless specific customization is required -- Keep dependencies up to date with PatternFly releases -- Follow semantic versioning for project dependencies -- Document any custom setup steps for team collaboration - -## Common Setup Scenarios - -- **New Project**: Use PatternFly React Seed -- **Existing React App**: Add PatternFly dependencies manually -- **Enterprise Environment**: Consider proxy and security requirements -- **Team Development**: Ensure consistent Node.js versions across team members \ No newline at end of file diff --git a/documentation/setup/development-environment.md b/documentation/setup/development-environment.md deleted file mode 100644 index a9a90e40..00000000 --- a/documentation/setup/development-environment.md +++ /dev/null @@ -1,236 +0,0 @@ -# Development Environment - -This guide covers the configuration of development tools and environment settings for optimal PatternFly React development. - -## Introduction - -A properly configured development environment enhances productivity and ensures consistent code quality when working with PatternFly React applications. This guide covers IDE setup, debugging tools, and development workflow optimization. - -## Related Files - -- [**Setup Guide**](./README.md) - Initial project setup -- [**Quick Start**](./quick-start.md) - Project initialization steps -- [**Styling Standards**](../guidelines/styling-standards.md) - CSS and styling configuration - -## Development Server Configuration - -### Default Configuration -- **Port**: `9000` (default for PatternFly React Seed) -- **Hot Reload**: Enabled by default -- **Source Maps**: Available for debugging -- **Proxy Settings**: Configurable for API integration - -### Server Management -```bash -# Start development server -npm run start:dev - -# Start in background (recommended for AI development) -npm run start:dev & - -# Stop server (if running in foreground) -Ctrl+C -``` - -### Environment Variables -Create a `.env` file in the project root for environment-specific settings: -```env -# Development server port -PORT=9000 - -# API endpoint configuration -REACT_APP_API_URL=http://localhost:3001 - -# Enable/disable specific features -REACT_APP_DEBUG_MODE=true -``` - -## IDE and Editor Configuration - -### Recommended Extensions (VS Code) -- **ES7+ React/Redux/React-Native snippets**: React development shortcuts -- **Auto Rename Tag**: Automatic HTML/JSX tag renaming -- **Bracket Pair Colorizer**: Visual bracket matching -- **GitLens**: Enhanced Git integration -- **Prettier**: Code formatting -- **ESLint**: Code linting - -### TypeScript Configuration -If using TypeScript with PatternFly: -```json -{ - "compilerOptions": { - "target": "es5", - "lib": ["dom", "dom.iterable", "es6"], - "allowJs": true, - "skipLibCheck": true, - "esModuleInterop": true, - "allowSyntheticDefaultImports": true, - "strict": true, - "forceConsistentCasingInFileNames": true, - "moduleResolution": "node", - "resolveJsonModule": true, - "isolatedModules": true, - "noEmit": true, - "jsx": "react-jsx" - }, - "include": ["src"] -} -``` - -## Debugging Configuration - -### Browser DevTools Setup -1. **React Developer Tools**: Install browser extension for React debugging -2. **PatternFly DevTools**: Use browser inspector to examine PatternFly classes -3. **Network Tab**: Monitor API calls and resource loading -4. **Console**: Check for PatternFly-specific warnings or errors - -### VS Code Debugging -Create `.vscode/launch.json` for debugging: -```json -{ - "version": "0.2.0", - "configurations": [ - { - "name": "Launch Chrome", - "request": "launch", - "type": "pwa-chrome", - "url": "http://localhost:9000", - "webRoot": "${workspaceFolder}/src", - "breakOnLoad": true, - "sourceMapPathOverrides": { - "webpack:///src/*": "${webRoot}/*" - } - } - ] -} -``` - -## Build and Testing Environment - -### Build Scripts -```bash -# Development build -npm run build:dev - -# Production build -npm run build - -# Analyze bundle size -npm run analyze -``` - -### Testing Configuration -```bash -# Run tests -npm test - -# Run tests with coverage -npm run test:coverage - -# Run tests in watch mode -npm run test:watch -``` - -## Package Management - -### Dependency Management -- **Core Dependencies**: PatternFly React components -- **Peer Dependencies**: React, React-DOM -- **Dev Dependencies**: Build tools, testing utilities - -### Version Compatibility -Ensure compatible versions between: -- React and PatternFly React -- PatternFly Core CSS and PatternFly React -- Node.js and npm versions - -### Update Strategy -```bash -# Check for outdated packages -npm outdated - -# Update PatternFly packages -npm update @patternfly/react-core @patternfly/react-table - -# Verify compatibility after updates -npm test -``` - -## Performance Optimization - -### Development Performance -- **Code Splitting**: Implement lazy loading for large components -- **Bundle Analysis**: Regular bundle size monitoring -- **Memory Management**: Monitor for memory leaks during development - -### Hot Module Replacement (HMR) -- Enabled by default in PatternFly React Seed -- Preserves component state during development -- Faster development iteration cycles - -## Environment-Specific Configuration - -### Development Environment -- Source maps enabled -- Detailed error messages -- Hot reloading active -- Debug mode available - -### Production Environment -- Minified bundles -- Optimized assets -- Error boundaries -- Performance monitoring - -## Workflow Integration - -### Git Hooks -Set up pre-commit hooks for code quality: -```json -{ - "husky": { - "hooks": { - "pre-commit": "lint-staged" - } - }, - "lint-staged": { - "src/**/*.{js,jsx,ts,tsx}": [ - "eslint --fix", - "prettier --write" - ] - } -} -``` - -### Continuous Integration -Configure CI/CD for: -- Automated testing -- Build verification -- Dependency security scanning -- Performance regression testing - -## Troubleshooting Development Environment - -### Common Issues -- **Port conflicts**: Change port in package.json or environment variables -- **Memory issues**: Increase Node.js memory limit -- **Slow builds**: Optimize webpack configuration -- **Hot reload failures**: Clear cache and restart development server - -### Performance Monitoring -- Monitor build times -- Track bundle size changes -- Profile component rendering -- Analyze network requests - -## Best Practices - -1. **Keep dependencies updated** but test thoroughly -2. **Use environment variables** for configuration -3. **Enable source maps** for debugging -4. **Configure linting and formatting** for consistency -5. **Set up proper debugging tools** for efficient development -6. **Monitor performance** during development -7. **Use version control** for environment configuration files \ No newline at end of file diff --git a/documentation/setup/quick-start.md b/documentation/setup/quick-start.md deleted file mode 100644 index a1380410..00000000 --- a/documentation/setup/quick-start.md +++ /dev/null @@ -1,129 +0,0 @@ -# Quick Start Guide - -This guide provides step-by-step instructions to get a PatternFly React application running quickly using the PatternFly React Seed. - -## Introduction - -The Quick Start process uses the official PatternFly React Seed repository to scaffold a complete application with pre-configured components, routing, and build tools. This is the fastest way to begin PatternFly development. - -## Related Files - -- [**Setup Guide**](./README.md) - Prerequisites and setup overview -- [**Development Environment**](./development-environment.md) - Environment configuration -- [**PatternFly Guidelines**](../guidelines/README.md) - Development best practices -- [**Common Issues**](../troubleshooting/common-issues.md) - Troubleshooting setup problems - -## Step-by-Step Instructions - -### Step 1: Clone the Repository - -```bash -git clone https://github.com/patternfly/patternfly-react-seed -``` - -**AI Note**: This command can be executed by AI assistants to initialize the project. - -### Step 2: Navigate to Project Directory - -```bash -cd patternfly-react-seed -``` - -**Important**: All subsequent npm commands must be run from this directory. - -### Step 3: Install Dependencies - -```bash -npm install -``` - -**AI Note**: -- AI can run this command after verifying Node.js and npm are properly installed -- This step downloads all required PatternFly and React dependencies -- May take several minutes depending on network speed - -### Step 4: Start Development Server - -```bash -npm run start:dev -``` - -**Important Considerations**: -- **User Recommendation**: Run this command in a separate terminal to keep it active -- **Default URL**: Development server typically runs at `http://localhost:9000` -- **Additional Information**: Check the project's [README.md](../../README.md) for server configuration details - -## Verification Steps - -After completing the setup: - -1. **Check Server Status**: Ensure the development server starts without errors -2. **Access Application**: Open `http://localhost:9000` in a web browser -3. **Verify Components**: Confirm PatternFly components are rendering correctly -4. **Test Hot Reload**: Make a small change to verify live reloading works - -## What You Get - -The PatternFly React Seed includes: - -### Pre-configured Components -- Page layout structure -- Navigation components -- Basic routing setup -- Example PatternFly components - -### Development Tools -- Webpack configuration -- Hot module replacement -- Development server -- Build scripts - -### Testing Setup -- Jest configuration -- Testing utilities -- Example test files - -## Next Steps - -1. **Explore the Codebase**: Review the generated file structure -2. **Read Documentation**: Check [PatternFly Guidelines](../guidelines/README.md) -3. **Start Development**: Begin building your application components -4. **Configure Environment**: Set up [Development Environment](./development-environment.md) tools - -## Common Post-Setup Tasks - -### Customizing the Application -- Update application name and metadata -- Configure routing for your specific needs -- Add custom components and pages - -### Development Workflow -- Set up version control (if not already done) -- Configure IDE/editor for PatternFly development -- Install additional development tools - -### Team Setup -- Share environment configuration -- Document custom setup steps -- Establish coding standards and practices - -## Troubleshooting Quick Start - -If you encounter issues during setup: - -1. **Verify Prerequisites**: Ensure Node.js and npm are properly installed -2. **Check Network**: Confirm internet connectivity for package downloads -3. **Clear Cache**: Try `npm cache clean --force` if installation fails -4. **Port Conflicts**: If port 9000 is in use, check for alternative ports -5. **Permission Issues**: On Unix systems, avoid using `sudo` with npm - -For detailed troubleshooting, see [Common Issues](../troubleshooting/common-issues.md). - -## Success Indicators - -You've successfully completed the Quick Start when: -- ✅ Repository is cloned without errors -- ✅ Dependencies install successfully -- ✅ Development server starts and runs -- ✅ Application loads in browser at `http://localhost:9000` -- ✅ PatternFly components are visible and styled correctly \ No newline at end of file diff --git a/documentation/troubleshooting/README.md b/documentation/troubleshooting/README.md deleted file mode 100644 index 222b9333..00000000 --- a/documentation/troubleshooting/README.md +++ /dev/null @@ -1,57 +0,0 @@ -# PatternFly Troubleshooting - -This directory contains troubleshooting guides and solutions for common PatternFly development issues. - -## Available Resources - -- **[Common Issues](./common-issues.md)** - Solutions to frequently encountered problems - -## Quick Troubleshooting Guide - -### Most Common Issues - -1. **Component Not Rendering** - - Check import statements - - Verify package installation - - Ensure proper CSS imports - -2. **Styling Issues** - - Verify PatternFly CSS is loaded - - Check for CSS conflicts - - Ensure proper theme application - -3. **Build Errors** - - Check Node.js version compatibility - - Verify package versions - - Clear node_modules and reinstall - -4. **Accessibility Issues** - - Review ARIA attributes - - Test with screen readers - - Validate keyboard navigation - -### Getting Help - -When encountering issues: - -1. **Check Common Issues**: Review the solutions in `common-issues.md` -2. **Search Documentation**: Use the [PatternFly documentation](https://www.patternfly.org/) -3. **Check GitHub Issues**: Search [PatternFly React issues](https://github.com/patternfly/patternfly-react/issues) -4. **Community Support**: Join [PatternFly Slack](https://patternfly.slack.com/) or [Forum](https://forum.patternfly.org/) - -### Related Resources - -- **[Setup Guide](../setup/README.md)** - Environment setup and configuration -- **[Guidelines](../guidelines/README.md)** - Development best practices -- **[Resources](../resources/README.md)** - External documentation and tools - -## Contributing Solutions - -If you find a solution to a common issue not covered here: - -1. Document the problem and solution -2. Add it to the appropriate troubleshooting file -3. Include code examples and context -4. Test the solution across different scenarios - -This helps the PatternFly community by sharing knowledge and reducing time spent on common issues. diff --git a/documentation/troubleshooting/common-issues.md b/documentation/troubleshooting/common-issues.md deleted file mode 100644 index db633576..00000000 --- a/documentation/troubleshooting/common-issues.md +++ /dev/null @@ -1,811 +0,0 @@ -# Common Issues - -This document covers frequently encountered problems and their solutions when working with PatternFly React applications. - -## Introduction - -PatternFly development can present various challenges ranging from setup issues to component-specific problems. This guide provides systematic approaches to diagnosing and resolving common issues that AI coders encounter when building PatternFly applications. - -## Related Files - -- [**Setup Guide**](../setup/README.md) - Initial setup troubleshooting -- [**External References**](../resources/external-links.md) - Additional troubleshooting resources - -## AI Coding Specific Issues - -### Component Generation Issues - -#### Issue: AI generates non-existent PatternFly components -```jsx -// ❌ AI might generate these (they don't exist) -Title -No data - -``` - -**Solutions**: -1. **Use correct v6 components**: - ```jsx - // ✅ Correct v6 components - import { Content, EmptyState, EmptyStateBody, EmptyStateHeader } from '@patternfly/react-core'; - - Title - - - - Description goes here - - ``` - -2. **Always verify component existence** - Check [PatternFly.org](https://www.patternfly.org/) before using - -#### Issue: AI uses CSS modules syntax -```jsx -// ❌ Wrong - This doesn't work in this project -
-``` - -**Solutions**: -1. **Use PatternFly utility classes**: - ```jsx - // ✅ Correct - Use PatternFly utilities -
- ``` - -2. **Use CSS-in-JS for custom styles**: - ```jsx - // ✅ Alternative - Inline styles when utilities don't exist -
- ``` - -#### Issue: AI uses inline styles instead of PatternFly utilities -```jsx -// ❌ Wrong - Avoid inline styles for layout/spacing -
-``` - -**Solutions**: -1. **Use proper PatternFly component composition**: - ```jsx - // ✅ Correct - Use proper component hierarchy - - - Content - Content description - - - ``` - -2. **For custom styles, use design tokens**: - ```jsx - // ✅ Only when component composition isn't sufficient -
- ``` - -### Accessibility Issues - -#### Issue: AI generates components without accessibility features -```jsx -// ❌ Not accessible - - Clickable content - -``` - -**Solutions**: -1. **Add proper ARIA attributes**: - ```jsx - // ✅ Accessible - e.key === 'Enter' && handleClick()} - > - Clickable content - - ``` - -2. **Use PatternFly's built-in accessibility props**: - ```jsx - // ✅ Use component's accessibility features - - ``` - -### Chart Integration Issues - -#### Issue: Wrong chart import paths -```bash -# Error message -Module not found: Can't resolve '@patternfly/react-charts' -``` - -**Solutions**: -1. **Use correct import paths**: - ```jsx - // ✅ Correct - Include /victory - import { ChartDonut, ChartLine } from '@patternfly/react-charts/victory'; - - // ❌ Wrong - Missing /victory - import { ChartDonut } from '@patternfly/react-charts'; - ``` - -2. **Install missing dependencies**: - ```bash - npm install @patternfly/react-charts victory - ``` - -#### Issue: AI uses wrong chart colors -```jsx -// ❌ Wrong - Hardcoded colors - -``` - -**Solutions**: -1. **Use PatternFly chart color tokens**: - ```jsx - // ✅ Correct - Use design tokens - const chartColors = [ - 'var(--pf-t-chart-color-blue-300)', - 'var(--pf-t-chart-color-green-300)', - 'var(--pf-t-chart-color-orange-300)' - ]; - - ``` - -### Chatbot Implementation Issues - -#### Issue: AI creates custom chat UI instead of using PatternFly Chatbot -```jsx -// ❌ Wrong - Custom chat implementation -
-
...
- -
-``` - -**Solutions**: -1. **Use PatternFly Chatbot components**: - ```jsx - // ✅ Correct - Use PatternFly Chatbot - import { Chatbot, ChatbotContent, MessageBox } from '@patternfly/chatbot/dist/dynamic/Chatbot'; - import '@patternfly/chatbot/dist/css/main.css'; - - - - - {/* Messages */} - - - - ``` - -2. **Follow official demo patterns** - Copy from [PatternFly Chatbot demos](https://www.patternfly.org/patternfly-ai/chatbot/overview) - -### Styling and Layout Issues - -#### Issue: AI mixes PatternFly versions -```jsx -// ❌ Wrong - Mixed versions -
-``` - -**Solutions**: -1. **Use PatternFly v6 only**: - ```jsx - // ✅ Correct - v6 only - - -
-``` - -**Solutions**: -1. **Use proper PatternFly component composition**: - ```jsx - // ✅ Proper spacing using ActionGroup component - - - - - ``` - -## Setup Issues - -### Node.js and npm Problems - -#### Issue: Command not found errors -```bash -# Error messages -'node' is not recognized as an internal or external command -'npm' is not recognized as an internal or external command -``` - -**Solutions**: -1. **Verify Installation**: - ```bash - # Check if Node.js is installed - node --version - npm --version - ``` - -2. **Reinstall Node.js**: - - Download from [https://nodejs.org/](https://nodejs.org/) - - Choose LTS version for stability - - Restart terminal after installation - -3. **PATH Configuration**: - ```bash - # Windows: Add to PATH environment variable - C:\Program Files\nodejs\ - - # macOS/Linux: Add to shell profile - export PATH="/usr/local/bin/node:$PATH" - ``` - -#### Issue: npm permission errors -```bash -# Error message -EACCES: permission denied, access '/usr/local/lib/node_modules' -``` - -**Solutions**: -1. **Use nvm (Recommended)**: - ```bash - # Install nvm - curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash - - # Install and use Node.js - nvm install node - nvm use node - ``` - -2. **Fix npm permissions**: - ```bash - # Create global directory - mkdir ~/.npm-global - npm config set prefix '~/.npm-global' - - # Add to PATH - export PATH=~/.npm-global/bin:$PATH - ``` - -### Project Setup Issues - -#### Issue: Git clone failures -```bash -# Error message -fatal: repository 'https://github.com/patternfly/patternfly-react-seed' not found -``` - -**Solutions**: -1. **Check Network Connection**: Verify internet connectivity -2. **Use HTTPS instead of SSH**: - ```bash - git clone https://github.com/patternfly/patternfly-react-seed - ``` -3. **Check Repository URL**: Verify the repository exists and URL is correct - -#### Issue: npm install failures -```bash -# Error messages -npm ERR! network request failed -npm ERR! peer dep missing -``` - -**Solutions**: -1. **Clear npm cache**: - ```bash - npm cache clean --force - ``` - -2. **Delete node_modules and reinstall**: - ```bash - rm -rf node_modules package-lock.json - npm install - ``` - -3. **Check npm registry**: - ```bash - npm config get registry - # Should return: https://registry.npmjs.org/ - ``` - -4. **Install with legacy peer deps**: - ```bash - npm install --legacy-peer-deps - ``` - -### Development Server Issues - -#### Issue: Port already in use -```bash -# Error message -Error: listen EADDRINUSE: address already in use :::9000 -``` - -**Solutions**: -1. **Find and kill process**: - ```bash - # Windows - netstat -ano | findstr :9000 - taskkill /PID /F - - # macOS/Linux - lsof -ti:9000 | xargs kill -9 - ``` - -2. **Use different port**: - ```bash - PORT=3001 npm run start:dev - ``` - -3. **Update package.json**: - ```json - { - "scripts": { - "start:dev": "webpack serve --port 3001" - } - } - ``` - -#### Issue: Development server not starting -```bash -# Error message -Module not found: Error: Can't resolve 'webpack-dev-server' -``` - -**Solutions**: -1. **Reinstall dependencies**: - ```bash - rm -rf node_modules package-lock.json - npm install - ``` - -2. **Check webpack configuration**: - ```javascript - // Verify webpack.config.js exists and is properly configured - ``` - -3. **Install missing dependencies**: - ```bash - npm install webpack webpack-dev-server --save-dev - ``` - -## Import and Module Issues - -### PatternFly Component Import Errors - -#### Issue: Module not found errors -```bash -# Error message -Module not found: Can't resolve '@patternfly/react-core' -``` - -**Solutions**: -1. **Install PatternFly packages**: - ```bash - npm install @patternfly/react-core @patternfly/react-table @patternfly/react-icons - ``` - -2. **Check import syntax**: - ```jsx - // Correct imports - import { Button, Card } from '@patternfly/react-core'; - import { Table, Thead, Tbody } from '@patternfly/react-table'; - import { UserIcon } from '@patternfly/react-icons'; - ``` - -3. **Verify package.json dependencies**: - ```json - { - "dependencies": { - "@patternfly/react-core": "^6.x.x", - "@patternfly/react-table": "^6.x.x", - "@patternfly/react-icons": "^6.x.x" - } - } - ``` - -#### Issue: Charts module not found -```bash -# Error message -Module not found: Can't resolve '@patternfly/react-charts/victory' -``` - -**Solutions**: -1. **Install charts dependencies**: - ```bash - npm install @patternfly/react-charts victory - ``` - -2. **Use correct import paths**: - ```jsx - // Correct chart imports - import { ChartDonut, ChartLine } from '@patternfly/react-charts/victory'; - ``` - -3. **Clear cache and reinstall**: - ```bash - rm -rf node_modules package-lock.json - npm install - ``` - -#### Issue: Chatbot module not found -```bash -# Error message -Module not found: Can't resolve '@patternfly/chatbot/dist/dynamic/Chatbot' -``` - -**Solutions**: -1. **Install chatbot package**: - ```bash - npm install @patternfly/chatbot - ``` - -2. **Import CSS**: - ```jsx - import '@patternfly/chatbot/dist/css/main.css'; - ``` - -3. **Use correct import paths**: - ```jsx - import { Chatbot } from '@patternfly/chatbot/dist/dynamic/Chatbot'; - ``` - -## Styling Issues - -### CSS and Class Problems - -#### Issue: PatternFly styles not applied -```bash -# Symptoms: Components appear unstyled or with default browser styles -``` - -**Solutions**: -1. **Import PatternFly CSS**: - ```jsx - // In your main App.js or index.js - import '@patternfly/react-core/dist/styles/base.css'; - ``` - -2. **Check CSS import order**: - ```jsx - // PatternFly CSS should be imported before custom CSS - import '@patternfly/react-core/dist/styles/base.css'; - import './custom-styles.css'; - ``` - -3. **Verify webpack CSS handling**: - ```javascript - // webpack.config.js - module.exports = { - module: { - rules: [ - { - test: /\.css$/, - use: ['style-loader', 'css-loader'] - } - ] - } - }; - ``` - -#### Issue: Wrong PatternFly version classes -```jsx -// Problem: Using old class names -
// v4 class -
// v5 class -``` - -**Solutions**: -1. **Use PatternFly v6 classes**: - ```jsx - // Correct v6 classes -
-
- ``` - -2. **Update class references**: - ```bash - # Find and replace old classes - grep -r "pf-c-" src/ - grep -r "pf-v5-" src/ - ``` - -3. **Use PatternFly components instead**: - ```jsx - // Instead of manual classes, use components - import { Button } from '@patternfly/react-core'; - - ``` - -#### Issue: PatternFly utility class styles not applied -```bash -# Symptoms: Adding utility classes (pf-v6-u-*) do not have any apparent effect -``` - -**Solutions**: -1. **Install patternfly package**: - ```bash - npm install @patternfly/patternfly - ``` - -2. **Import PatternFly Utility CSS**: - ```jsx - // In your main App.js or index.js - import '@patternfly/patternfly/patternfly-addons.css'; - ``` - -3. **Verify webpack CSS handling**: - ```javascript - // webpack.config.js - module.exports = { - module: { - rules: [ - { - test: /\.css$/, - use: ['style-loader', 'css-loader'] - } - ] - } - }; - ``` - -### Layout and Responsive Issues - -#### Issue: Components not responsive -```jsx -// Problem: Fixed widths and heights -
-``` - -**Solutions**: -1. **Use PatternFly responsive utilities**: - ```jsx -
- ``` - -2. **Implement responsive patterns**: - ```jsx -
-
- Content -
-
- ``` - -3. **Use container-based sizing**: - ```jsx - const [dimensions, setDimensions] = useState({ width: 0, height: 0 }); - - useEffect(() => { - const updateDimensions = () => { - if (containerRef.current) { - const { width, height } = containerRef.current.getBoundingClientRect(); - setDimensions({ width, height }); - } - }; - - updateDimensions(); - window.addEventListener('resize', updateDimensions); - return () => window.removeEventListener('resize', updateDimensions); - }, []); - ``` - -## Component-Specific Issues - -### Dropdown Clipping Issues - -#### Issue: Dropdown menu gets clipped -```jsx -// Problem: Dropdown appears cut off in scrollable containers -``` - -**Solutions**: -1. **Use appendTo prop**: - ```jsx - document.body, - position: 'right', - enableFlip: true - }} - > - ``` - -2. **Configure positioning**: - ```jsx - - ``` - -### Table Performance Issues - -#### Issue: Slow rendering with large datasets -```jsx -// Problem: Table becomes unresponsive with 1000+ rows -``` - -**Solutions**: -1. **Implement pagination**: - ```jsx - import { Pagination } from '@patternfly/react-core'; - - const [page, setPage] = useState(1); - const [perPage, setPerPage] = useState(20); - const paginatedData = data.slice((page - 1) * perPage, page * perPage); - ``` - -2. **Use virtualization**: - ```jsx - import { DndProvider, useDrag, useDrop } from 'react-dnd'; - import { HTML5Backend } from 'react-dnd-html5-backend'; - import { Table, Thead, Tbody, Tr, Th, Td } from '@patternfly/react-table'; - - const DraggableRow = ({ id, text, index, moveRow }) => { - // ... existing code ... - ``` - -3. **Optimize re-renders**: - ```jsx - const MemoizedRow = React.memo(({ item }) => ( -

{item.name}{item.email}