Metadata-Version: 2.4
Name: dash-ant-design
Version: 0.1.2
Summary: Ant Design components for Plotly Dash
Author-email: C0deBeez <ethan.zhang2016@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/c0debeez/dash-antd-components
Project-URL: Bug Reports, https://github.com/c0debeez/dash-antd-components/issues
Project-URL: Source, https://github.com/c0debeez/dash-antd-components
Classifier: Framework :: Dash
Classifier: Framework :: Flask
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dash>=3.0.0
Dynamic: license-file

# Dash Ant Design

Ant Design components for Plotly Dash.

## Installation

```bash
pip install dash-ant-design
```

## Usage

Import the generated Python package as `dash_antd_components`:

```python
from dash import Dash, Input, Output, callback, html

import dash_antd_components as dac

app = Dash(__name__)

app.layout = dac.ConfigProvider(
    dac.Space(
        [
            dac.Input(id="name", placeholder="Your name", value="Dash"),
            dac.Button("Greet", id="greet", type="primary"),
            html.Div(id="message"),
        ],
        direction="vertical",
        size="middle",
    )
)


@callback(Output("message", "children"), Input("greet", "n_clicks"), Input("name", "value"))
def greet(n_clicks, name):
    if not n_clicks:
        return "Click the button to start."
    return f"Hello, {name or 'Dash'}!"


if __name__ == "__main__":
    app.run(debug=True)
```

### Chart

`dac.Chart` wraps AntV G2 v5. Pass a JSON-safe G2 options dictionary through the `options` prop:

```python
chart_options = {
    "type": "interval",
    "data": [
        {"category": "A", "value": 40},
        {"category": "B", "value": 65},
        {"category": "C", "value": 52},
    ],
    "encode": {"x": "category", "y": "value", "color": "category"},
    "axis": {"y": {"title": "Value"}},
}

chart = dac.Chart(id="sales-chart", options=chart_options, style={"height": 360})
```

### Sheet

`dac.Sheet` wraps AntV S2. Provide `dataCfg` with fields and records, plus optional S2 `options`:

```python
sheet_data = {
    "fields": {"rows": ["province"], "columns": ["type"], "values": ["sales"]},
    "data": [
        {"province": "Zhejiang", "type": "Furniture", "sales": 1200},
        {"province": "Zhejiang", "type": "Office", "sales": 950},
        {"province": "Jiangsu", "type": "Furniture", "sales": 880},
    ],
    "meta": [
        {"field": "province", "name": "Province"},
        {"field": "type", "name": "Category"},
        {"field": "sales", "name": "Sales"},
    ],
}

sheet = dac.Sheet(
    id="sales-sheet",
    dataCfg=sheet_data,
    options={"width": 720, "height": 360},
)
```

## Documentation development

The documentation application and Vercel root live in [`docs/`](docs/).
Python dependencies and tasks use `docs/pyproject.toml` and the shared workspace
lock; docs-only JavaScript tooling uses `docs/package.json` and the root pnpm
lockfile. After rebuilding components, run
`uv run --package dash-ant-design-docs --group dev poe -C docs build` and
`uv run --package dash-ant-design-docs --group dev poe -C docs check` from the root.

The persisted `usage-preferences` store is the source of truth for the Dash UI locale. A saved locale wins;
otherwise the initial page selects the first supported browser language and falls back to `zh-cn`. Dash callbacks
pass that locale explicitly to the Babel translation service. Ant Design receives the same locale through
`ConfigProvider`; API handlers remain stateless and do not depend on request-local translation globals.

Component pages use `/components/<component>` and standalone demos use `/examples/<demo-id>`.
Legacy `/components#<demo-id>` links are normalized automatically.

## Documentation MCP server

The deployed documentation application exposes a read-only Dash MCP server at
`https://<documentation-host>/_mcp`. It provides version information, component
and property discovery, localized API documentation, and runnable example source
through the following tools:

- `dac_get_library_info`
- `dac_list_components`
- `dac_get_component`
- `dac_search_props`
- `dac_get_examples`
- `dac_search_chart_examples`

Examples of MCP tool arguments:

```json
{"name": "dac_get_component", "arguments": {"component": "Button", "locale": "en-us"}}
{"name": "dac_get_component", "arguments": {"component": "EventSource", "locale": "zh-cn", "include_documentation": true}}
{"name": "dac_search_props", "arguments": {"query": "loading", "component": "Button"}}
{"name": "dac_get_examples", "arguments": {"component": "Chart", "locale": "en-us"}}
```

`dac_get_component` returns property metadata by default. Set
`include_documentation` to `true` to also receive the page's localized Markdown
prose in `documentation`, without frontmatter or internal demo/API directives.
Example source remains available separately through `dac_get_examples`.

`dac_search_chart_examples` searches a bundled, JSON-safe G2 example index by
natural-language chart intent. The docs OpenAI chart generator uses the same
local index before calling the model. Rebuild the corpus from AntV's Content
Retrieval Service when upstream examples change:

```bash
cd docs && uv run --group dev poe generate-chart-retrieval
```

The generated corpus is checked into
`docs/src/resources/chart/examples.json`; runtime searches do not call the AntV
service or download an embedding model.

Add the published documentation server to Codex:

```bash
codex mcp add dash-antd-components-docs \
  --url https://<documentation-host>/_mcp
```

Or add it to Claude Code:

```bash
claude mcp add dash-antd-components-docs \
  --transport http \
  --scope user \
  https://<documentation-host>/_mcp
```

Other Streamable HTTP MCP clients can use:

```json
{
  "mcpServers": {
    "dash-antd-components-docs": {
      "type": "http",
      "url": "https://<documentation-host>/_mcp"
    }
  }
}
```

## Python typing

Run `pnpm run build:backends` to regenerate Python types from the TypeScript
props and the focused overrides in `dash_prop_typing.py`. A TypeScript-checker
pass restores omitted union branches and literal values before Dash regenerates
the bindings and development validators. Validators recognize serialized Dash
component slots as well as React nodes. The build then derives
instance attribute annotations from the generated constructor signatures and
emits the `py.typed` package marker. No separate handwritten `.pyi` files or
per-component attribute lists are maintained.

Instance declarations are inside `typing.TYPE_CHECKING`: they help IDEs but do
not create runtime attributes or change defaults. An omitted Dash property may
still be absent at runtime. Types that remain `Any` in the generated signature
remain permissive; improve their source metadata rather than patching the output.

## React compatibility

The package requires Python >=3.10 and Dash >=3.0.0. The build and TypeScript
definitions use React/ReactDOM 18.3.1. React is provided by Dash and is not
bundled with the components; importing `dash_antd_components` does not override
the application's React runtime. React 18 is the default supported baseline,
and React 19 remains optional when supplied by the installed Dash release.

The docs application requires Python >=3.13 and pins Dash 4.5.0 for reproducible
development and tests; this does not raise the published component's minimum
Dash version. It uses Dash's default React 18.3.1 runtime. See
[docs setup](docs/README.md) for installation and startup.

Video.js packages remain version-aligned. No `REACT_VERSION` override is needed
for normal startup. To explicitly select the build baseline:

```bash
REACT_VERSION=18.3.1 python app.py
```
