diff --git a/README.md b/README.md index 7801807..c60dbc9 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,44 @@ -# dash-mui-charts +
-[![PyPI version](https://badge.fury.io/py/dash-mui-charts.svg)](https://badge.fury.io/py/dash-mui-charts) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + + + 2plot.ai + -A Dash component library wrapping [MUI X Charts](https://mui.com/x/react-charts/) for creating beautiful, interactive data visualizations in Python. +# dash-mui-charts — MUI X charts for Dash -## Features +**Interactive [MUI X](https://mui.com/x/) charts, tree views and time pickers for [Plotly Dash](https://dash.plotly.com).** -- **LineChart** - Line and area charts with zoom/pan, multiple axes, and stacking -- **BarChart** - Vertical/horizontal bars with stacking, labels, dataset mode, and zoom/brush (Pro) -- **CandlestickChart** - OHLC candlestick charts with volume overlay, reference lines, and click events -- **PieChart** - Pie, donut, and nested/concentric pie charts -- **ScatterChart** - Scatter/point charts with z-axis color mapping and voronoi interaction -- **CompositeChart** - Layer scatter + line plots on a single surface with zoom/pan -- **Heatmap** - Matrix visualizations with customizable color scales -- **SparklineChart** - Compact inline charts for dashboards and tables -- **LiveTradingChart** - Real-time streaming charts for live data visualization -- **TreeView** - Data-driven rich tree with controlled selection, expansion, and label editing -- **SimpleTreeView** - Lightweight JSX-driven tree for navigation sidebars -- **TreeViewPro** - Drag-and-drop reordering, lazy loading, per-item slider + kebab controls (Pro) -- **TimeClock** - Inline clock-face time picker (MUI X Date & Time Pickers) +13 components · full Python type hints · clicks, zoom, selection and edits as Dash callbacks · dark mode · Community and Pro tiers. + +[![PyPI version](https://img.shields.io/pypi/v/dash-mui-charts?color=blue)](https://pypi.org/project/dash-mui-charts/) +[![Python](https://img.shields.io/pypi/pyversions/dash-mui-charts)](https://pypi.org/project/dash-mui-charts/) +[![Dash 3.3+](https://img.shields.io/badge/Dash-3.3%2B-1a1a2e?logo=plotly&logoColor=white)](https://dash.plotly.com/) +[![CI](https://github.com/pip-install-python/dash-mui-charts/actions/workflows/ci.yml/badge.svg)](https://github.com/pip-install-python/dash-mui-charts/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/WEnZR35mrK) +[![YouTube](https://img.shields.io/badge/YouTube-%402plotai-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/channel/UC6Bmo0t0ZUpU_xKBYW0bJuQ) + +**[Documentation](https://muicharts.2plot.dev)** · [Discord](https://discord.gg/WEnZR35mrK) · [YouTube](https://www.youtube.com/channel/UC6Bmo0t0ZUpU_xKBYW0bJuQ) · [GitHub](https://github.com/pip-install-python/dash-mui-charts) + +
+ +_Maintained by **[Pip Install Python LLC](https://pip-install-python.com)**._ + +
+ +--- + +## Overview + +**dash-mui-charts** wraps [MUI X Charts](https://mui.com/x/react-charts/), [MUI X Tree View](https://mui.com/x/react-tree-view/) and the MUI X Date & Time Pickers' TimeClock as first-class Dash components. Author charts in Python, and get every interaction back as a callback property. + +- **13 components** — nine chart types, three tree views, and a clock-face time picker. +- **Callbacks-first** — `clickData`, `axisClickData`, `highlightedItem`, `hoverIndex`, `zoomData`, selection and edit events all arrive as Dash inputs; controlled props (`highlightedItem`, `expandedItems`, `value`, …) work in both directions for synchronized, cross-chart UIs. +- **Dark mode by construction** — components watch the Mantine color-scheme attribute and re-theme live. +- **Functions-as-props** — axis `valueFormatter` and alert formatters accept `{'function': 'name', 'options': {...}}` resolved from a JS registry, mirroring the dash-mantine-components pattern. +- **Community and Pro tiers** — Community features need no license; zoom/pan, sliders, toolbars, brush, Heatmap and TreeViewPro extras light up with a [MUI X Pro license key](#mui-x-pro-licensing). ## Installation @@ -27,6 +46,8 @@ A Dash component library wrapping [MUI X Charts](https://mui.com/x/react-charts/ pip install dash-mui-charts ``` +Requires `dash>=3.3`. See [Dash compatibility](#dash-compatibility) for the tested matrix. + ## Quick Start ```python @@ -36,7 +57,6 @@ from dash_mui_charts import LineChart, PieChart app = Dash(__name__) app.layout = html.Div([ - # Simple Line Chart LineChart( series=[ {'data': [2, 5, 3, 8, 1, 9], 'label': 'Sales'}, @@ -45,8 +65,6 @@ app.layout = html.Div([ xAxis=[{'data': ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'], 'scaleType': 'band'}], height=300, ), - - # Simple Pie Chart PieChart( data=[ {'id': 0, 'value': 35, 'label': 'Marketing'}, @@ -62,511 +80,158 @@ if __name__ == '__main__': app.run(debug=True) ``` -## Components - -### LineChart +## Documentation -Create line and area charts with rich interactivity. +### 📚 **[muicharts.2plot.dev](https://muicharts.2plot.dev)** -```python -from dash_mui_charts import LineChart - -LineChart( - id='my-line-chart', - series=[ - { - 'data': [2, 5.5, 2, 8.5, 1.5, 5], - 'label': 'Series A', - 'color': '#1976d2', - 'area': True, # Fill area under line - 'curve': 'monotoneX', # Smooth curve - }, - ], - xAxis=[{'data': [1, 2, 3, 4, 5, 6], 'scaleType': 'linear'}], - yAxis=[{'label': 'Value'}], - height=400, - grid={'horizontal': True, 'vertical': False}, -) -``` +41 pages of live, interactive examples — every chart family with working callbacks, two props playgrounds, and an [API reference](https://muicharts.2plot.dev/api) whose props tables are generated from the components' own metadata. Every docs page also serves an LLM-friendly version at `//llms.txt`. -**Key Props:** -| Prop | Type | Description | -|------|------|-------------| -| `series` | list | Array of line configurations (data, label, color, area, curve, stack) | -| `xAxis` | list | X-axis configurations (data, scaleType, label) | -| `yAxis` | list | Y-axis configurations (label, position, min, max) | -| `zoom` | list | Zoom state for controlled zoom (requires Pro license) | -| `showSlider` | bool | Show zoom slider below chart | -| `grid` | dict | Grid line configuration | -| `height` | int | Chart height in pixels | - -**Output Props (for callbacks):** -- `clickData` - Data from click events -- `zoomData` - Current zoom state -- `n_clicks` - Click counter +Run it locally: ---- +```bash +git clone https://github.com/pip-install-python/dash-mui-charts.git +cd dash-mui-charts +pip install -r requirements.txt +# markdown2dash pins gunicorn<22, against the CVE-driven gunicorn>=23 floor in +# requirements.txt. pip cannot resolve both, so it installs without its +# dependency graph — every one of them is in requirements.txt already. +pip install --no-deps markdown2dash==0.1.2 +pip install -e . +python run.py # http://127.0.0.1:7666 +``` -### BarChart +## Components -Create vertical and horizontal bar charts with stacking, labels, and dataset mode. +| Component | Category | What it is | Tier | +|--------------------|----------|------------------------------------------------------------------------|-----------------| +| `LineChart` | Charts | Line/area charts, biaxial axes, reference lines, zoom/pan, brush | Community / Pro | +| `BarChart` | Charts | Vertical/horizontal bars, stacking, bar labels, dataset mode, zoom | Community / Pro | +| `CandlestickChart` | Charts | OHLC candlesticks with volume overlay and reference lines | Community / Pro | +| `PieChart` | Charts | Pie, donut, and nested pies with controlled highlighting | Community | +| `ScatterChart` | Charts | Scatter plots, z-axis color mapping, voronoi interaction | Community | +| `CompositeChart` | Charts | Scatter + line series layered on one surface, multi-axis | Community / Pro | +| `Heatmap` | Charts | Matrix visualization with continuous/piecewise color scales | Pro | +| `SparklineChart` | Charts | Compact inline charts for dashboards, KPI cards and tables | Community | +| `LiveTradingChart` | Charts | Real-time streaming OHLCV simulation with forecast and alerts | Community / Pro | +| `TreeView` | Trees | Data-driven RichTreeView: selection, expansion, inline label editing | Community | +| `SimpleTreeView` | Trees | JSX-driven tree for navigation sidebars and static hierarchies | Community | +| `TreeViewPro` | Trees | Drag-reorder, lazy loading, per-item slider and kebab controls | Pro | +| `TimeClock` | Pickers | Inline clock-face time picker | Community | + +## MUI X Pro licensing + +dash-mui-charts itself is MIT. **Pro-tier features run on MUI X Pro**, which requires [a commercial license from MUI](https://mui.com/x/introduction/licensing/) — pass your key to any component via the `licenseKey` prop: ```python +import os from dash_mui_charts import BarChart BarChart( - id='my-bar-chart', - series=[ - {'data': [4, 3, 5], 'label': 'Group A', 'color': '#1976d2'}, - {'data': [1, 6, 3], 'label': 'Group B', 'color': '#388e3c'}, - ], - xAxis=[{'data': ['Q1', 'Q2', 'Q3'], 'scaleType': 'band'}], - height=350, - grid={'horizontal': True}, -) - -# Stacked horizontal bars with rounded corners -BarChart( - series=[ - {'data': [30, 25, 40], 'label': 'Online', 'stack': 'channel', 'color': '#1976d2'}, - {'data': [20, 15, 25], 'label': 'Retail', 'stack': 'channel', 'color': '#42a5f5'}, - ], - yAxis=[{'data': ['2023', '2024', '2025'], 'scaleType': 'band'}], - layout='horizontal', - borderRadius=6, - height=300, -) - -# Dataset mode (no data duplication) -BarChart( - dataset=[ - {'month': 'Jan', 'sales': 100, 'returns': 5}, - {'month': 'Feb', 'sales': 150, 'returns': 8}, - ], - xAxis=[{'dataKey': 'month', 'scaleType': 'band'}], - series=[ - {'dataKey': 'sales', 'label': 'Sales'}, - {'dataKey': 'returns', 'label': 'Returns'}, - ], - height=350, -) -``` - -**Key Props:** -| Prop | Type | Description | -|------|------|-------------| -| `series` | list | Bar series (data, label, color, stack, barLabel, barLabelPlacement) | -| `dataset` | list | Table-format data for dataKey-based series | -| `xAxis` | list | X-axis config (data, scaleType, categoryGapRatio, barGapRatio) | -| `layout` | str | 'vertical' (default) or 'horizontal' | -| `borderRadius` | int | Rounded bar corners (pixels) | -| `referenceLines` | list | Horizontal/vertical reference markers | -| `initialZoom` | list | Initial zoom state (Pro) | -| `showSlider` | bool | Show zoom slider (Pro) | -| `showToolbar` | bool | Show toolbar (Pro) | - -**Output Props:** -- `clickData` - Bar click event (seriesId, dataIndex) -- `axisClickData` - Axis area click event -- `highlightedItem` - Currently hovered item -- `zoomData` - Zoom state (Pro) -- `n_clicks` - Click counter - ---- - -### CandlestickChart - -Create OHLC candlestick charts for financial data visualization. - -```python -from dash_mui_charts import CandlestickChart - -# Array format -CandlestickChart( - id='my-candles', - series=[{ - 'data': [ - [100, 110, 95, 105], # [open, high, low, close] - [105, 115, 100, 112], - [112, 120, 108, 118], - ], - 'upColor': '#4caf50', - 'downColor': '#f44336', - }], - xAxis=[{'data': ['Mon', 'Tue', 'Wed']}], - yAxis=[{'label': 'Price ($)'}], - grid={'horizontal': True}, - height=400, -) - -# Dataset format with volume -CandlestickChart( - dataset=[ - {'date': '2025-01-02', 'open': 100, 'high': 110, 'low': 95, 'close': 105, 'volume': 1200}, - {'date': '2025-01-03', 'open': 105, 'high': 115, 'low': 100, 'close': 112, 'volume': 1500}, - ], - series=[{ - 'datasetKeys': {'open': 'open', 'high': 'high', 'low': 'low', 'close': 'close'}, - 'volumeKey': 'volume', - 'upColor': '#4caf50', - 'downColor': '#f44336', - }], - xAxis=[{'dataKey': 'date'}], - showVolume=True, - height=450, -) -``` - -**Key Props:** -| Prop | Type | Description | -|------|------|-------------| -| `series` | list | OHLC series with data or datasetKeys, upColor, downColor | -| `dataset` | list | Row objects for dataset mode | -| `showVolume` | bool | Show volume bars overlay | -| `bodyWidthRatio` | float | Candle body width ratio (0-1, default 0.6) | -| `wickWidth` | int | Wick line width in pixels (default 2) | -| `referenceLines` | list | Support/resistance reference lines | - -**Output Props:** -- `clickData` - Candle click event (dataIndex, open, high, low, close) -- `zoomData` - Zoom state (Pro) - ---- - -### PieChart - -Create pie, donut, and nested pie charts. - -```python -from dash_mui_charts import PieChart - -# Simple Donut Chart -PieChart( - data=[ - {'id': 0, 'value': 35, 'label': 'Chrome'}, - {'id': 1, 'value': 25, 'label': 'Safari'}, - {'id': 2, 'value': 20, 'label': 'Firefox'}, - {'id': 3, 'value': 20, 'label': 'Edge'}, - ], - innerRadius=60, # Creates donut hole - cornerRadius=5, - paddingAngle=2, - height=300, -) - -# Nested Pie Chart (Multi-Series) -PieChart( - series=[ - { - 'data': inner_ring_data, - 'innerRadius': 0, - 'outerRadius': 80, - 'highlightScope': {'fade': 'global', 'highlight': 'item'}, - }, - { - 'data': outer_ring_data, - 'innerRadius': 90, - 'outerRadius': 120, - 'highlightScope': {'fade': 'global', 'highlight': 'item'}, - }, - ], - height=400, -) -``` - -**Key Props:** -| Prop | Type | Description | -|------|------|-------------| -| `data` | list | Pie data for single series (id, value, label, color) | -| `series` | list | Multi-series config for nested pies | -| `innerRadius` | int/str | Inner radius (>0 creates donut) | -| `outerRadius` | int/str | Outer radius | -| `startAngle` | int | Start angle in degrees (default: 0) | -| `endAngle` | int | End angle in degrees (default: 360) | -| `arcLabel` | str | Label type: 'value', 'label', 'formattedValue' | -| `cornerRadius` | int | Rounded corners on slices | -| `paddingAngle` | int | Gap between slices in degrees | - -**Output Props:** -- `clickData` - Clicked slice data (id, label, value, seriesIndex) -- `highlightedItem` - Currently hovered item -- `n_clicks` - Click counter - ---- - -### ScatterChart - -Create scatter/point charts with multi-series support and z-axis color mapping. - -```python -from dash_mui_charts import ScatterChart - -ScatterChart( - id='my-scatter', - series=[ - { - 'id': 'group-a', - 'label': 'Group A', - 'data': [ - {'x': 1, 'y': 5, 'id': 0}, - {'x': 2, 'y': 8, 'id': 1}, - {'x': 3, 'y': 6, 'id': 2}, - ], - 'color': '#1976d2', - 'markerSize': 6, - }, - ], - voronoiMaxRadius=30, - height=400, -) -``` - -**Key Props:** -| Prop | Type | Description | -|------|------|-------------| -| `series` | list | Scatter series with data [{x, y, id}], color, markerSize | -| `zAxis` | list | Z-axis config for color mapping | -| `voronoiMaxRadius` | int | Proximity radius for hover interaction | -| `dataset` | list | Table-format data for datasetKeys pattern | -| `renderer` | str | 'svg' (default) or 'svg-batch' for large datasets | - -**Output Props:** -- `clickData` - Click event with seriesId, dataIndex, x, y -- `highlightedItem` - Currently hovered item -- `n_clicks` - Click counter - ---- - -### CompositeChart - -Layer scatter and line plots on a single chart surface. - -> **Note:** Zoom/pan features require MUI X Pro license. - -```python -from dash_mui_charts import CompositeChart - -CompositeChart( - id='my-composite', - series=[ - { - 'type': 'line', - 'id': 'baseline', - 'label': 'Baseline', - 'data': [50, 55, 48, 62, 58], - 'color': '#66bb6a', - 'area': True, - }, - { - 'type': 'scatter', - 'id': 'anomalies', - 'label': 'Anomalies', - 'data': [{'x': 1, 'y': 80, 'id': 0}, {'x': 3, 'y': 25, 'id': 1}], - 'color': '#e53935', - 'markerSize': 6, - }, - ], - xAxis=[{'data': [0, 1, 2, 3, 4], 'scaleType': 'linear'}], - height=400, + licenseKey=os.environ['MUI_PRO_API_KEY'], + series=[...], + xAxis=[{'data': [...], 'scaleType': 'band', 'zoom': {'minSpan': 8}}], + showSlider=True, # Pro: zoom slider ) ``` -**Key Props:** -| Prop | Type | Description | -|------|------|-------------| -| `series` | list | Array of series with `type` ('scatter' or 'line') | -| `xAxis` | list | X-axis config (supports `scaleType: 'time'` with epoch ms) | -| `yAxis` | list | Y-axis config (supports multi-axis with `id` and `position`) | -| `referenceLines` | list | Horizontal/vertical reference markers | -| `initialZoom` | list | Initial zoom state (Pro) | -| `showSlider` | bool | Show zoom slider (Pro) | -| `showToolbar` | bool | Show toolbar (Pro) | - -**Output Props:** -- `clickData` - Click event with type, seriesId, dataIndex -- `highlightedItem` - Currently hovered item -- `zoomData` - Current zoom state -- `n_clicks` - Click counter - ---- - -### Heatmap +Without a key, Pro features render with MUI's unlicensed watermark — components degrade, they never crash. Community features never need a key. -Create matrix visualizations with color-coded cells. +## API reference -> **Note:** Requires MUI X Pro license for full functionality. +The **[/api page](https://muicharts.2plot.dev/api)** lists every prop of all 13 components, generated from the components' own metadata so it always matches the installed version. The props you will meet everywhere: -```python -from dash_mui_charts import Heatmap - -Heatmap( - data=[ - [0, 0, 10], [0, 1, 20], [0, 2, 30], - [1, 0, 40], [1, 1, 50], [1, 2, 60], - [2, 0, 70], [2, 1, 80], [2, 2, 90], - ], - xAxis={'data': ['Mon', 'Tue', 'Wed'], 'scaleType': 'band'}, - yAxis={'data': ['Morning', 'Afternoon', 'Evening'], 'scaleType': 'band'}, - colorScale={ - 'type': 'continuous', - 'min': 0, - 'max': 100, - 'colors': ['#e3f2fd', '#1976d2'], - }, - height=300, -) -``` +| Prop | Type | Description | +|---------------------------------------|------|-------------------------------------------------------------------| +| `id` | str | Dash callback identity — available on every component | +| `licenseKey` | str | MUI X Pro key — enables Pro features per component | +| `clickData` / `axisClickData` | dict | Callback **outputs**: what was clicked, with series/axis context | +| `highlightedItem` | dict | Controlled highlight — works as callback input AND output | +| `hoverIndex` / `hoverValue` | — | Sparkline hover stream for synchronized displays | +| `selectedItems` / `expandedItems` | — | Tree selection/expansion — controlled or uncontrolled | +| `sx` | dict | MUI system styling passed straight to the underlying component | -**Key Props:** -| Prop | Type | Description | -|------|------|-------------| -| `data` | list | Array of [x, y, value] tuples | -| `xAxis` | dict | X-axis band scale configuration | -| `yAxis` | dict | Y-axis band scale configuration | -| `colorScale` | dict | Color mapping (continuous or piecewise) | -| `cellStyle` | str/dict | Cell styling ('rounded' or detailed config) | - -**Output Props:** -- `clickData` - Clicked cell data (x, y, value, color) -- `highlightedItem` - Currently hovered cell -- `n_clicks` - Click counter - ---- +## Dash compatibility -### SparklineChart +The **package** targets **Dash 3.3 and up**; the **documentation site** needs Dash 4.1+ (its llms.txt engine pins `dash>=4.1`). Both floors are verified, not assumed, in [GitHub Actions](.github/workflows/ci.yml) on every push and PR: -Create compact inline charts for dashboards. +- the docs site boots and smoke-tests on **Dash 4.1.0 / 4.2.0 / 4.3.0 / 4.4.1** (Python 3.10–3.13), rebuilding the component bundle and Python wrappers from source in each cell; +- the wheel installs into a clean venv with **nothing but Dash present** on Python 3.9 → 3.13, plus a dedicated `dash==3.3.0` floor install; +- the production Docker image is built, booted secretless, and probed by the same network battery that checks the live site after every deploy. -```python -from dash_mui_charts import SparklineChart - -SparklineChart( - data=[1, 4, 2, 5, 7, 2, 4, 6], - plotType='line', # or 'bar' - color='#1976d2', - area=True, - height=40, - width=150, - showTooltip=True, -) -``` - -**Key Props:** -| Prop | Type | Description | -|------|------|-------------| -| `data` | list | Numeric values (required) | -| `plotType` | str | 'line' or 'bar' | -| `color` | str | Line/bar color | -| `area` | bool | Fill area under line | -| `curve` | str | Curve interpolation method | -| `showTooltip` | bool | Enable hover tooltips | - -**Output Props:** -- `highlightedItem` - Current highlight state -- `hoverIndex` - Index of hovered point -- `hoverValue` - Value at hovered point -- `n_hovers` - Hover counter - ---- - -## License Requirements - -| Component | Community (Free) | Pro License Required | -|-----------|------------------|---------------------| -| LineChart | Basic features | Zoom & Pan | -| BarChart | Basic features | Zoom, Brush & Toolbar | -| CandlestickChart | Basic features | Zoom & Toolbar | -| PieChart | All features | - | -| ScatterChart | All features | - | -| CompositeChart | Basic layering | Zoom & Pan | -| Heatmap | - | All features | -| SparklineChart | All features | - | -| LiveTradingChart | All features | - | - -To use Pro features, obtain a license from [MUI](https://mui.com/x/introduction/licensing/) and pass it via the `licenseKey` prop: - -```python -LineChart( - licenseKey='YOUR_MUI_X_PRO_LICENSE_KEY', - # ... other props -) +```bash +python scripts/smoke_test.py # the per-version harness, standalone ``` -## Interactive Examples - -Run the demo application to explore all components: +## Development ```bash git clone https://github.com/pip-install-python/dash-mui-charts.git cd dash-mui-charts + +# JS toolchain (only needed when changing src/lib/components) +npm install +npm run build # webpack bundle + regenerated Python wrappers +npm run validate-init # all 13 components generated and importable + +# Python pip install -r requirements.txt -python app.py +pip install --no-deps markdown2dash==0.1.2 # pins gunicorn<22; see above +pip install -e . +python run.py # docs on :7666 + +# Test +pytest tests/ # 80 checks, zero secrets by design +python scripts/smoke_test.py # routes, layouts, JS parse +python scripts/route_parity.py --charts-only # every live example, id and callback intact +python scripts/check_release.py # version drift, stale bundle, packaging + +# Build a distribution +python -m build ``` -Visit `http://127.0.0.1:7666` to see: -- Basic and advanced line chart examples -- Bar chart demos: stacking, dataset mode, interactions, Pro zoom -- Candlestick OHLC charts with volume overlay and click events -- Pie chart property explorer with nested pies -- Scatter chart with z-axis color mapping and voronoi interaction -- Composite charts layering scatter + line with zoom/pan -- Heatmap configuration playground -- Sparkline styling options -- Live trading real-time chart +The React sources in `src/lib/components/*.react.js` are the source of truth — the Python classes in `dash_mui_charts/` are generated from their PropTypes by `dash-generate-components`. The built bundle and wrappers are committed so git-based deploys (Render) work without a node toolchain. -## Development +**After editing `src/lib/components/*.react.js` you must run `npm run build`** and commit the regenerated bundle and wrappers in the same commit — `check_release.py` compares git commit timestamps and flags a bundle older than its source. The version lives in two files: `package.json` (which `setup.py` reads) and `dash_mui_charts/package-info.json` (which `__version__` reads, regenerated by the build); `check_release.py` fails if they drift. -### Prerequisites +## Releasing -- Python 3.8+ -- Node.js 16+ -- npm +Tag-driven. `git tag -a vX.Y.Z && git push origin vX.Y.Z` runs [`release.yml`](.github/workflows/release.yml): it asserts the tag matches `package.json`, re-runs the consistency and smoke checks, builds, publishes to PyPI over **OIDC trusted publishing** (no API token stored anywhere), and opens a GitHub Release with that version's CHANGELOG section attached. A `workflow_dispatch` dry run publishes to TestPyPI instead. -### Setup +## Deployment -```bash -# Install dependencies -npm install -pip install -r requirements.txt +The documentation site runs at **[muicharts.2plot.dev](https://muicharts.2plot.dev)** on Render. The repo ships a `render.yaml` blueprint and `Dockerfile` — create a Render Blueprint from the repo, fill the `sync: false` secrets in the dashboard, point the `muicharts.2plot.dev` CNAME at the service, and it auto-deploys on push to main with a `/healthz` health check. -# Build components -npm run build +The canonical origin lives in exactly one place — `DEFAULT_BASE_URL` in `lib/constants.py` (override per-environment with `APP_BASE_URL`). `templates/index.html` carries `__CANONICAL_ORIGIN__` tokens that `run.py` substitutes at startup, so the canonical link, `og:url`, the JSON-LD, `sitemap.xml`, `robots.txt` and the llms.txt links cannot drift apart. -# Run development server -python app.py -``` +## Requirements -### Build Process +- Python >= 3.9 (the documentation site itself needs >= 3.10 — see below) +- Dash >= 3.3 (the documentation site needs >= 4.1) +- Node.js >= 18 — only to rebuild the JS bundle +- A [MUI X Pro license](https://mui.com/x/introduction/licensing/) — only for Pro-tier features -```bash -# Full build (JS + Python wrappers) -npm run build +The **package** needs only Python 3.9+ and Dash 3.3+; that range is verified in CI. Running the **documentation site** from source additionally needs Python 3.10+ (`python-frontmatter` imports `typing.TypeGuard`) and Dash 4.1+. Neither floor applies to `pip install dash-mui-charts`. -# Watch mode for development -npm run start -``` +## Community & support -## Contributing +- 💬 [Discord](https://discord.gg/WEnZR35mrK) — questions and showcase +- ▶️ [YouTube @2plotai](https://www.youtube.com/channel/UC6Bmo0t0ZUpU_xKBYW0bJuQ) — tutorials +- 🐛 [GitHub Issues](https://github.com/pip-install-python/dash-mui-charts/issues) — bugs and feature requests -Contributions are welcome! Please feel free to submit a Pull Request. +Come build with us. -1. Fork the repository -2. Create your feature branch (`git checkout -b feature/AmazingFeature`) -3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request +## More from Pip Install Python LLC -## Resources +dash-mui-charts is one of several tools built and maintained by **Pip Install Python LLC**: -- [MUI X Charts Documentation](https://mui.com/x/react-charts/) -- [Dash Documentation](https://dash.plotly.com) -- [Dash Component Boilerplate](https://github.com/plotly/dash-component-boilerplate) +| Project | What it is | +|------------------------------------------------------------------|---------------------------------------------------| +| 📊 **[2plot.ai](https://2plot.ai)** | The network hub — data apps, analytics, sign-in | +| 🎬 **[2plot.media](https://2plot.media)** | Videography application | +| 🧩 **[2plot.dev](https://2plot.dev)** | The full Dash component catalogue | +| 🤖 **[ai-agent.buzz](https://ai-agent.buzz)** | Infinite AI canvas | +| ⛵️ **[PiratesBargain](https://piratesbargain.com/shop)** | E-commerce / digital commerce | ## License -Pip Install Python LLC MIT License - see [LICENSE](LICENSE) for details. - -## Author - -**Pip Install Python** -- GitHub: [@pip-install-python](https://github.com/pip-install-python) \ No newline at end of file +MIT — see [LICENSE](LICENSE). dash-mui-charts is an independent Dash wrapper around [MUI X](https://mui.com/x/), which is its own project under its own licenses: the Community features wrap MIT-licensed MUI X packages, and Pro-tier features require your own commercial MUI X license. Built by [Pip Install Python](https://github.com/pip-install-python).