@reliability-design/web 1.0.2 → 1.0.6

package/dist/components/rel-chart/README.md

@@ -0,0 +1,286 @@
+# rel-chart
+
+A lightweight, accessible chart component built with Lit for the Reliability Design System. Supports bar and line charts with interactive tooltips.
+
+## Features
+
+- Bar charts (grouped)
+- Line charts with points
+- Interactive tooltips on hover/focus
+- Grid and axis labels
+- Legend
+- Responsive sizing
+- Full keyboard navigation
+- Token-driven styling
+- Reduced motion support
+
+## Usage
+
+### Property-based (Recommended)
+
+```javascript
+const chart = document.querySelector('rel-chart');
+
+chart.data = [
+  { month: 'Jan', desktop: 186, mobile: 80 },
+  { month: 'Feb', desktop: 305, mobile: 200 },
+  { month: 'Mar', desktop: 237, mobile: 120 },
+  { month: 'Apr', desktop: 73, mobile: 190 },
+  { month: 'May', desktop: 209, mobile: 130 },
+  { month: 'Jun', desktop: 214, mobile: 140 }
+];
+
+chart.series = [
+  { key: 'desktop', label: 'Desktop' },
+  { key: 'mobile', label: 'Mobile' }
+];
+
+chart.xKey = 'month';
+```
+
+### Attribute-based (Simple demos)
+
+```html
+<rel-chart
+  type="bar"
+  x-key="month"
+  series-json='[{"key":"desktop","label":"Desktop"},{"key":"mobile","label":"Mobile"}]'
+  data-json='[
+    {"month":"Jan","desktop":186,"mobile":80},
+    {"month":"Feb","desktop":305,"mobile":200},
+    {"month":"Mar","desktop":237,"mobile":120}
+  ]'
+></rel-chart>
+```
+
+### Bar Chart
+
+```html
+<rel-chart type="bar" x-key="date"></rel-chart>
+```
+
+### Line Chart
+
+```html
+<rel-chart type="line" x-key="date"></rel-chart>
+```
+
+### Custom Height
+
+```html
+<rel-chart height="400"></rel-chart>
+```
+
+### Without Grid
+
+```html
+<rel-chart show-grid="false"></rel-chart>
+```
+
+### Date Formatting
+
+```html
+<rel-chart format-x="date" locale="en-US"></rel-chart>
+```
+
+### Custom Colors
+
+```javascript
+chart.series = [
+  {
+    key: 'desktop',
+    label: 'Desktop',
+    colorToken: 'var(--rel-colors-blue-primary)'
+  },
+  {
+    key: 'mobile',
+    label: 'Mobile',
+    colorToken: 'var(--rel-colors-green-primary)'
+  }
+];
+```
+
+## Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `type` | `"bar" \| "line"` | `"bar"` | Chart type |
+| `height` | `number` | `320` | Chart height in pixels |
+| `x-key` | `string` | `""` | Property name for x-axis values |
+| `series-json` | `string` | `""` | JSON string of series configuration |
+| `data-json` | `string` | `""` | JSON string of chart data |
+| `show-grid` | `boolean` | `true` | Show background grid |
+| `show-axis` | `boolean` | `true` | Show axis labels |
+| `show-legend` | `boolean` | `true` | Show legend |
+| `stacked` | `boolean` | `false` | Stack bars (bar chart only, not implemented in v1) |
+| `format-x` | `"date" \| "string" \| "number"` | `"string"` | X-axis value format |
+| `locale` | `string` | `"en-US"` | Locale for date formatting |
+| `disabled` | `boolean` | `false` | Disable interactions |
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | `Array<Record<string, unknown>>` | Chart data (preferred over data-json) |
+| `series` | `SeriesConfig[]` | Series configuration (preferred over series-json) |
+
+### SeriesConfig
+
+```typescript
+interface SeriesConfig {
+  key: string;           // Property name in data
+  label?: string;        // Display label
+  colorToken?: string;   // CSS variable or color token
+}
+```
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `rel-hover` | `{ index: number, datum: object, seriesKey?: string }` | Fired when hovering over a data point |
+
+## Keyboard Navigation
+
+- **Tab**: Navigate between data points
+- **Enter/Space**: Show tooltip for focused point
+- Each bar/point is focusable and shows tooltip on focus
+
+## CSS Parts
+
+Use `::part()` to customize chart appearance:
+
+```css
+rel-chart::part(container) {
+  background: #f5f5f5;
+}
+
+rel-chart::part(bar) {
+  rx: 4; /* Rounded corners */
+}
+
+rel-chart::part(tooltip) {
+  background: rgba(0, 0, 0, 0.9);
+  color: white;
+}
+```
+
+Available parts:
+- `container` - Chart container
+- `svg` - SVG element
+- `grid` - Grid lines
+- `axis` - Axis lines and labels
+- `bar` - Bar elements
+- `line` - Line paths
+- `point` - Line chart points
+- `legend` - Legend container
+- `tooltip` - Tooltip overlay
+
+## Data Format
+
+### Simple Data
+
+```javascript
+[
+  { month: 'Jan', value: 100 },
+  { month: 'Feb', value: 150 },
+  { month: 'Mar', value: 120 }
+]
+```
+
+### Multi-Series Data
+
+```javascript
+[
+  { date: '2024-01', desktop: 186, mobile: 80, tablet: 45 },
+  { date: '2024-02', desktop: 305, mobile: 200, tablet: 150 },
+  { date: '2024-03', desktop: 237, mobile: 120, tablet: 90 }
+]
+```
+
+## Examples
+
+### Complete Bar Chart Example
+
+```html
+<rel-chart
+  id="sales-chart"
+  type="bar"
+  height="360"
+></rel-chart>
+
+<script>
+  const chart = document.getElementById('sales-chart');
+
+  chart.xKey = 'month';
+  chart.data = [
+    { month: 'January', desktop: 186, mobile: 80 },
+    { month: 'February', desktop: 305, mobile: 200 },
+    { month: 'March', desktop: 237, mobile: 120 },
+    { month: 'April', desktop: 73, mobile: 190 },
+    { month: 'May', desktop: 209, mobile: 130 },
+    { month: 'June', desktop: 214, mobile: 140 }
+  ];
+
+  chart.series = [
+    { key: 'desktop', label: 'Desktop', colorToken: 'var(--rel-colors-blue-primary)' },
+    { key: 'mobile', label: 'Mobile', colorToken: 'var(--rel-colors-green-primary)' }
+  ];
+
+  chart.addEventListener('rel-hover', (e) => {
+    console.log('Hovering:', e.detail);
+  });
+</script>
+```
+
+### Complete Line Chart Example
+
+```html
+<rel-chart
+  id="trend-chart"
+  type="line"
+  height="300"
+  format-x="date"
+></rel-chart>
+
+<script>
+  const chart = document.getElementById('trend-chart');
+
+  chart.xKey = 'date';
+  chart.data = [
+    { date: '2024-01-01', revenue: 4200 },
+    { date: '2024-01-08', revenue: 4500 },
+    { date: '2024-01-15', revenue: 4100 },
+    { date: '2024-01-22', revenue: 4800 },
+    { date: '2024-01-29', revenue: 5200 }
+  ];
+
+  chart.series = [
+    { key: 'revenue', label: 'Revenue', colorToken: 'var(--rel-colors-green-success)' }
+  ];
+</script>
+```
+
+## Accessibility
+
+- Charts use semantic SVG with proper ARIA labels
+- All interactive elements are keyboard accessible
+- Tooltips appear on both hover and focus
+- Respects `prefers-reduced-motion` user preference
+- Color is not the only way to distinguish data (labels provided)
+
+## Styling
+
+The component uses design tokens from the Reliability Design System. All colors, spacing, and typography are inherited from CSS variables.
+
+Key tokens used:
+- `--rel-colors-*` for all colors
+- `--rel-spacing-*` for spacing
+- `--rel-fontSizes-*`, `--rel-fontWeights-*` for typography
+- `--rel-borders-*` for borders and radius
+- `--rel-shadows-*` for shadows
+- Default series colors use system color tokens
+
+## Browser Support
+
+Works in all modern browsers with ES2020 support and native Web Components.

package/dist/components/rel-chart/index.ts

@@ -0,0 +1 @@
+export * from "./rel-chart";