feat: improve accessibility, add missing chart options and view component libraries support

Author: sncalvo

CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - Unreleased
+
+### Added
+- **Accessibility (ARIA + keyboard)**: `title:` and `description:` options on charts, `role="img"` and `aria-label` on SVG elements, `aria-hidden` on decorative elements (grid, crosshair, reference lines), `aria-label` on data points
+- **Empty state**: Centered "No data available" message (customizable via `empty_message:`) when data array is empty, with placeholder icon
+- **Data labels**: `c.data_label format: :currency, position: :top` to render formatted values directly on bars, lines, scatter dots, and pie slices
+- **Sparklines**: `trackplot_sparkline @data, key: :revenue` helper for inline mini-charts (line, bar, area) via `<trackplot-sparkline>` custom element
+- **Stacked bars**: `c.bar :revenue, stack: "main"` now renders stacked bars using `d3.stack()`, matching the existing stacked area pattern
+- **Dual Y-axis**: `c.axis :y, axis_id: :right` creates a right-side axis; series bind via `y_axis: :right`
+- **Export to PNG/SVG**: `element.exportPNG()` and `element.exportSVG()` methods on `<trackplot-chart>` for downloading charts
+- **ViewComponent support**: `Trackplot::Component` (optional, requires `view_component` gem)
+- **Phlex support**: `Trackplot::PhlexComponent` (optional, requires `phlex` gem)
+- **Brush/zoom**: `c.brush(axis: :x)` for interactive range selection on cartesian charts with mini preview
+- **Real-time data append**: `element.appendData(newPoints, { maxPoints: 50 })` for live dashboard updates with `trackplot:data-update` event
+- **Heatmap chart type**: `c.heatmap(x_key: :day, y_key: :hour, value_key: :count)` for density/intensity visualization
+- **Treemap chart type**: `c.treemap(value_key: :size, label_key: :name)` for hierarchical data with optional `parent_key` grouping
+
+## [0.1.0] - 2025-01-01
+
+### Added
+- Initial release with 10 chart types: Line, Bar, Area (with stacking), Scatter, Pie/Donut, Radar, Horizontal Bar, Candlestick, Funnel
+- Declarative Ruby DSL via `trackplot_chart` helper with block syntax
+- D3.js rendering via `<trackplot-chart>` custom element
+- Theming system with 4 presets (default, dark, vibrant, minimal) and custom hash support
+- Tooltip with crosshair for cartesian charts, hover tooltips for pie/radar/funnel
+- Legend component with configurable position
+- Grid lines (horizontal/vertical)
+- Reference lines (horizontal/vertical) with labels, colors, and dash styles
+- Format helpers (`:currency`, `:percent`, `:compact`, `:decimal`, `:integer`) for axes and tooltips
+- Click events via `trackplot:click` custom event with datum detail
+- Turbo support: stable `id:` option, `turbo:before-cache` cleanup, `updateData()` / `updateConfig()` public API
+- ResizeObserver for responsive re-rendering
+- Importmap integration via Rails engine
+- Animated transitions with configurable `animate:` option
+- DataAdapter: normalizes Hash, Array, ActiveRecord::Relation inputs to string-keyed hashes

CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to Trackplot
+
+Thank you for considering contributing to Trackplot! This guide will help you get started.
+
+## Development Setup
+
+1. **Clone the repository**
+
+```bash
+git clone https://github.com/eagerworks/trackplot.git
+cd trackplot
+```
+
+2. **Install dependencies**
+
+```bash
+bundle install
+```
+
+3. **Run the test suite**
+
+```bash
+bundle exec rake
+```
+
+Or run tests directly:
+
+```bash
+ruby -Ilib -Itest -e "Dir['test/**/*_test.rb'].each { |f| require File.expand_path(f) }"
+```
+
+4. **Run the dummy Rails app** (for visual testing)
+
+```bash
+cd test/dummy
+bin/rails server
+```
+
+Then open `http://localhost:3000/charts` in your browser.
+
+## Running the Linter
+
+We use [Standard Ruby](https://github.com/standardrb/standard) for code formatting:
+
+```bash
+bundle exec standardrb
+```
+
+To auto-fix violations:
+
+```bash
+bundle exec standardrb --fix
+```
+
+## Project Structure
+
+```
+lib/trackplot/
+  chart_builder.rb          # Main DSL builder
+  sparkline_builder.rb      # Sparkline mini-chart builder
+  data_adapter.rb           # Normalizes input data
+  theme.rb                  # Theme presets and resolution
+  engine.rb                 # Rails engine setup
+  components/               # One file per chart/component type
+    base.rb, line.rb, bar.rb, area.rb, pie.rb, ...
+
+app/
+  assets/javascripts/trackplot/
+    index.js                # Complete JS engine (D3 rendering)
+  helpers/trackplot/
+    chart_helper.rb         # View helpers
+
+test/
+  trackplot/
+    chart_builder_test.rb   # Ruby DSL tests
+  dummy/                    # Rails dummy app for integration testing
+```
+
+## How to Contribute
+
+### Reporting Bugs
+
+- Open an issue at https://github.com/eagerworks/trackplot/issues
+- Include: Ruby/Rails version, browser, minimal reproduction steps, expected vs actual behavior
+
+### Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Run the full test suite (`bundle exec rake`)
+6. Run the linter (`bundle exec standardrb`)
+7. Commit with a descriptive message
+8. Push to your fork and open a Pull Request
+
+### Coding Conventions
+
+- Follow Standard Ruby style
+- Ruby components follow the existing pattern: inherit from `Components::Base`, implement `to_config`
+- JS renderers follow the pattern: `renderXxx(g, data, ..., theme, chartElement)` function
+- Keep the JS in a single `index.js` file (no build step)
+- Test Ruby DSL output (config hashes), not HTML rendering
+- Use `transform_keys` (stdlib) instead of `symbolize_keys` (ActiveSupport) in gem code
+
+### Adding a New Chart Type
+
+1. Create `lib/trackplot/components/my_chart.rb` inheriting from `Base`
+2. Add autoload in `lib/trackplot.rb`
+3. Add DSL method in `chart_builder.rb`
+4. Add renderer function in `index.js`
+5. Register the type in `ALL_SERIES_TYPES` constant
+6. Add tooltip support if applicable
+7. Add tests in `chart_builder_test.rb`
+8. Add demo in `test/dummy/app/views/charts/index.html.erb`