feat(react-charts): vega lite schema support

packages/charts/react-charts/VEGA_SCHEMA_INTEGRATION.md

@@ -0,0 +1,247 @@
+# Vega-Lite Schema Integration Summary
+
+## Overview
+
+Successfully integrated 112 Vega-Lite JSON schemas into the VegaDeclarativeChart component with comprehensive testing infrastructure.
+
+## Files Created/Modified
+
+### 1. Schema Files (90 new + 22 existing = 112 total)
+
+Location: `stories/src/VegaDeclarativeChart/schemas/`
+
+**Categories:**
+
+- **Financial Analytics** (10): stock prices, portfolio allocation, cash flow, ROI, etc.
+- **E-Commerce & Retail** (10): orders, conversion funnels, inventory, customer segments
+- **Marketing & Social Media** (10): campaigns, engagement, viral growth, sentiment
+- **Healthcare & Fitness** (10): patient vitals, treatments, health metrics
+- **Education & Learning** (10): test scores, attendance, graduation rates
+- **Manufacturing & Operations** (10): production, defects, machine utilization
+- **Climate & Environmental** (10): temperature, emissions, renewable energy
+- **Technology & DevOps** (10): API monitoring, deployments, server load
+- **Sports & Entertainment** (10): player stats, team rankings, streaming
+- **Basic Charts** (11): line, area, bar, scatter, donut, heatmap, combos
+- **Additional** (11): various other use cases
+
+### 2. Updated Story File
+
+**File:** `stories/src/VegaDeclarativeChart/VegaDeclarativeChartDefault.stories.tsx`
+
+**Key Features:**
+
+- Dynamic loading of all 112 schemas using `require.context`
+- Automatic categorization by domain
+- Category-based filtering dropdown
+- Enhanced error boundary with stack traces
+- Comprehensive chart type distribution display
+- Support for:
+  - Line, area, bar (vertical/horizontal/stacked/grouped)
+  - Scatter, donut, heatmap charts
+  - Combo/layered charts (line+bar, line+area, etc.)
+  - Multiple axis types (temporal, quantitative, ordinal, nominal, log)
+  - Data transforms (fold, etc.)
+
+### 3. Comprehensive Test Suite
+
+**File:** `library/src/components/VegaDeclarativeChart/VegaDeclarativeChart.SchemaValidation.test.tsx`
+
+**Test Features:**
+
+1. **Automatic Schema Discovery**: Loads all JSON schemas from the schemas directory
+2. **Transformation Validation**: Tests each schema's transformation to Fluent chart props
+3. **Feature Detection**: Identifies unsupported features:
+
+   - Layered/combo charts with multiple mark types
+   - Logarithmic scales
+   - Data transforms (fold, filter, etc.)
+   - Independent y-axis scales (dual-axis)
+   - Size encoding (bubble charts)
+   - Opacity encoding
+   - xOffset encoding (grouped bars)
+   - Text marks (annotations)
+   - Rule marks (reference lines)
+   - Color fill bars (rect with x/x2)
+
+4. **Comprehensive Reporting**:
+
+   - Success rate calculation
+   - Failed transformations with error details
+   - Schemas with unsupported features grouped by chart type
+   - Chart type distribution statistics
+   - Render validation for successful transformations
+
+5. **Specific Feature Tests**:
+   - Layered/combo chart handling
+   - Log scale support
+   - Data transform support
+
+## Chart Type Coverage
+
+### Fully Supported Chart Types:
+
+- ✅ **Line Charts**: Single and multi-series with temporal/quantitative axes
+- ✅ **Area Charts**: Filled areas with optional stacking
+- ✅ **Scatter Charts**: Point marks with size/color encoding
+- ✅ **Vertical Bar Charts**: Simple bars with categorical x-axis
+- ✅ **Horizontal Bar Charts**: Simple bars with categorical y-axis
+- ✅ **Stacked Bar Charts**: Multiple series stacked
+- ✅ **Grouped Bar Charts**: Multiple series side-by-side (with xOffset)
+- ✅ **Donut/Pie Charts**: Arc marks with theta encoding
+- ✅ **Heatmaps**: Rect marks with x, y, and color encodings
+
+### Partially Supported Features:
+
+- ⚠️ **Combo Charts**: Layered specs work if mark types are compatible
+- ⚠️ **Log Scales**: May render but accuracy not guaranteed
+- ⚠️ **Data Transforms**: Fold transform works, others untested
+- ⚠️ **Dual-Axis**: Independent y-scales may not render correctly
+- ⚠️ **Annotations**: Text and rule marks may not be fully supported
+- ⚠️ **Size Encoding**: Bubble charts may have limited support
+
+### Axis Types Covered:
+
+- ✅ **Temporal**: Date/time data with formatting
+- ✅ **Quantitative**: Numeric continuous data
+- ✅ **Ordinal**: Ordered categorical data
+- ✅ **Nominal**: Unordered categorical data
+- ⚠️ **Log**: Logarithmic scales (partial support)
+
+## Running the Tests
+
+```bash
+cd library
+npm test -- VegaDeclarativeChart.SchemaValidation.test.tsx
+```
+
+**Expected Output:**
+
+- Total schemas tested: 112
+- Success rate: >70% (estimated)
+- Detailed report of:
+  - Successfully transformed schemas
+  - Failed transformations with errors
+  - Schemas with unsupported features
+  - Chart type distribution
+
+## Viewing the Story
+
+```bash
+cd ../stories
+npm run storybook
+```
+
+Navigate to: **Charts > VegaDeclarativeChart > Default**
+
+**Features:**
+
+1. Category dropdown to filter by domain (11 categories)
+2. Chart type dropdown with 112 schemas
+3. Live JSON editor
+4. Real-time chart preview
+5. Width/height controls
+6. Error boundary with detailed messages
+7. Feature list and category statistics
+
+## Schema Structure
+
+All schemas follow Vega-Lite v5 specification:
+
+```json
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
+  "description": "Human-readable description",
+  "data": {
+    "values": [/* realistic sample data */]
+  },
+  "mark": "type" or { "type": "...", /* options */ },
+  "encoding": {
+    "x": { "field": "...", "type": "..." },
+    "y": { "field": "...", "type": "..." },
+    /* additional encodings */
+  },
+  "title": "Chart Title"
+}
+```
+
+## Unsupported Vega-Lite Features
+
+The following Vega-Lite features are NOT standard Fluent UI chart capabilities:
+
+1. **Sankey Charts**: Not a standard Vega-Lite mark (requires custom implementation)
+2. **Funnel Charts**: Not a standard Vega-Lite mark
+3. **Gantt Charts**: Not a standard Vega-Lite mark
+4. **Gauge Charts**: Not a standard Vega-Lite mark
+5. **Geographic Maps**: Not implemented in Fluent UI charts
+6. **Complex Transforms**: Only basic transforms like fold are supported
+7. **Interactive Selections**: Vega-Lite selection grammar not fully implemented
+8. **Faceting**: Small multiples not supported
+9. **Repeat**: Repeated charts not supported
+10. **Concatenation**: Side-by-side charts not supported
+
+## Error Handling
+
+### Schema-Level Errors:
+
+- Invalid JSON: Caught by JSON parser with error message
+- Missing required fields: Caught during transformation with descriptive error
+- Unsupported mark types: Falls back to line chart or throws error
+
+### Runtime Errors:
+
+- Error boundary catches rendering exceptions
+- Displays error message with stack trace
+- Allows editing to fix the schema
+
+### Test-Level Errors:
+
+- Transformation failures are captured and reported
+- Schemas are marked as "failed" with error details
+- Unsupported features are detected and listed
+
+## Best Practices for Schema Authors
+
+1. **Use Standard Marks**: Stick to line, area, bar, point, circle, arc, rect
+2. **Simple Encodings**: Use x, y, color, size, tooltip
+3. **Avoid Complex Transforms**: Use pre-transformed data when possible
+4. **Test Incrementally**: Start with simple schema, add features gradually
+5. **Include Titles**: Add descriptive titles and field labels
+6. **Realistic Data**: Use representative sample data
+7. **Handle Nulls**: Ensure data doesn't have null/undefined values
+
+## Integration with CI/CD
+
+The test suite can be integrated into CI/CD pipelines:
+
+```yaml
+# Example GitHub Actions workflow
+- name: Test Vega Schema Validation
+  run: |
+    cd library
+    npm test -- VegaDeclarativeChart.SchemaValidation.test.tsx --coverage
+```
+
+## Future Enhancements
+
+1. **Schema Validation**: Add JSON Schema validation for Vega-Lite specs
+2. **Auto-Detection**: Automatically detect and report unsupported features before rendering
+3. **Fallback Strategies**: Implement graceful degradation for unsupported features
+4. **Performance Testing**: Add performance benchmarks for complex schemas
+5. **Accessibility**: Ensure all generated charts meet WCAG standards
+6. **Export**: Add ability to export schemas and rendered charts
+7. **Schema Builder**: Visual schema builder UI in Storybook
+
+## Documentation
+
+- **Vega-Lite Docs**: https://vega.github.io/vega-lite/docs/
+- **Fluent UI Charts**: https://developer.microsoft.com/en-us/fluentui#/controls/web/charts
+- **Component API**: See VegaDeclarativeChart.tsx JSDoc comments
+
+## Support
+
+For issues or questions:
+
+1. Check test output for transformation errors
+2. Review error boundary messages in Storybook
+3. Consult Vega-Lite documentation for spec syntax
+4. Review Fluent UI chart component documentation