Skip to content

README.md

Latest commit

 

History

History
274 lines (222 loc) · 8.51 KB

README.md

File metadata and controls

274 lines (222 loc) · 8.51 KB

Charts Rules

Essential rules for PatternFly Charts implementation using Victory.js and ECharts.

Installation Rules

Required Installation

# ✅ 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
// ✅ 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

// 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

# 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:

    // Change this:
import { ChartDonut } from '@patternfly/react-charts';

// To this:
import { ChartDonut } from '@patternfly/react-charts/victory';

  2. Install Victory dependency:

    npm install victory

  3. Clear cache and reinstall:

    rm -rf node_modules package-lock.json
npm install

  4. Verify installation:

    # 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
// ✅ Correct - Use PatternFly color tokens
const chartColors = [
  '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)'
];

<ChartDonut data={data} colorScale={chartColors} />

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
// ✅ 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
// ✅ Required accessibility pattern
<ChartDonut
  data={data}
  ariaDesc="Chart showing user distribution"
  ariaTitle="User Status Chart"
  tabIndex={0}
  role="img"
/>

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
// ✅ Required state handling
if (isLoading) return <Spinner />;
if (error) return <EmptyState><EmptyStateHeader titleText="Chart error" /></EmptyState>;
if (!data?.length) return <EmptyState><EmptyStateHeader titleText="No data" /></EmptyState>;

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
// ✅ Required integration pattern
import { Card, CardTitle, CardBody } from '@patternfly/react-core';

<Card>
  <CardTitle>Chart Title</CardTitle>
  <CardBody>
    <ChartDonut data={data} />
  </CardBody>
</Card>

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
// ✅ Required performance patterns
const LazyChart = lazy(() => import('./HeavyChart'));

<Suspense fallback={<Spinner />}>
  <LazyChart />
</Suspense>

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

# Symptoms: Chart color variables (--pf-v6-chart-color-blue-100, --pf-t--chart--color--blue--300) are not defined

Solutions:

  1. Install patternfly package:

    npm install @patternfly/patternfly

  2. Import PatternFly Charts CSS:

    // In your main App.js or index.js
import '@patternfly/patternfly/patternfly-charts.css';

Quick Reference

Reference Documentation

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.