### Example with Forwarded Plotly Events

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/README.md

This example demonstrates how to use `PBPlotWithEvents` to capture and react to various Plotly events such as selection, click, hover, and cursor movement. It also shows how to initialize a Plotly chart within a Stipple application.

```julia
using Stipple, Stipple.ReactiveTools
using StipplePlotly
using PlotlyBase

@app Example begin
    @mixin plot::PBPlotWithEvents
    @in plot_cursor = Dict{String, Any}()

    @onchange isready begin
        isready || return
        p = Plot(scatter(y=1:10))
        plot.layout = p.layout
        plot.data = p.data
    end

    @onchange plot_selected begin
        haskey(plot_selected, "points") && @info "Selection: $(getindex.(plot_selected["points"], "pointIndex"))"
    end

    @onchange plot_click begin
        @info "$plot_click"
    end

    @onchange plot_hover begin
        @info "hovered over $(plot_hover["points"][1]["x"]):$(plot_hover["points"][1]["y"])"
        # @info "$plot_hover"
    end

    @onchange plot_cursor begin
        @info "cursor moved to $(plot_cursor["cursor"]["x"]):$(plot_cursor["cursor"]["y"])"
        # @info "$plot_cursor"
    end
end

@mounted Example watchplots()

# the keyword argument 'keepselection' (default = false) controls whether the selection outline shall be removed after selection
function ui()
    cell(class = "st-module", [
        plotly(:plot, syncevents = true, keepselection = false),
    ])
end

@page("/", ui, model = Example)
```

--------------------------------

### Configure Plot Interaction and Toolbar

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Set up chart interaction features like responsiveness, scroll zoom, and mode bar visibility. This configuration is rendered as a Dict for embedding.

```julia
using StipplePlotly

config = PlotConfig(
    responsive = true,
    scrollzoom = true,
    displaymodebar = true,
    displaylogo = false,
    editable = false,
    staticplot = false,
    toimage_format = "png",
    toimage_filename = "my_chart",
    toimage_width = 1200,
    toimage_height = 600,
    toimage_scale = 2
)
```

```julia
# Rendered as a Dict for embedding in plot()
Dict(config)
```

--------------------------------

### Advanced Plotly Chart with Click Events

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Demonstrates building a complex Plotly chart using the PlotlyBase DSL within a Stipple app. It includes handling click events on the chart to log information about the clicked point, such as trace and index.

```julia
using Stipple, Stipple.ReactiveTools, StipplePlotly, PlotlyBase

@app AdvancedApp begin
    @mixin p::PBPlotWithEvents

    @onchange isready begin
        # Build with PlotlyBase DSL
        p = Plot(
            [
                scatter(x=1:50, y=cumsum(randn(50)), name="Walk 1", mode="lines"),
                scatter(x=1:50, y=cumsum(randn(50)), name="Walk 2", mode="lines",
                        line=attr(dash="dash"))
            ],
            Layout(
                title  = attr(text="Random Walks"),
                xaxis  = attr(title="Step"),
                yaxis  = attr(title="Value"),
                legend = attr(orientation="h")
            )
        )
    end

    @onchange p_click begin
        isempty(p_click) && return
        pt = p_click["points"][1]
        @info "Clicked trace=$(pt["curveNumber"])", index=$(pt["pointIndex"])
    end
end

@mounted AdvancedApp watchplots()

function ui()
    cell([plotly(:p, syncevents = true)])
end

@page("/", ui, model = AdvancedApp)
```

--------------------------------

### Writable Plotly Chart with Events

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Defines a Stipple app with a writable Plotly chart using `PBPlotWithEvents`. This allows both server and client to update chart data and layout. The chart is initialized when the app is ready.

```julia
using Stipple, Stipple.ReactiveTools, StipplePlotly, PlotlyBase

# Writable plot: server or client may update data/layout
@app WritableApp begin
    @mixin chart::PBPlotWithEvents
    # Equivalent fields:
    #   chart            ::R{PlotlyBase.Plot}
    #   chart_selected   ::R{Dict{String,Any}}
    #   chart_hover      ::R{Dict{String,Any}}
    #   chart_click      ::R{Dict{String,Any}}
    #   chart_relayout   ::R{Dict{String,Any}}

    @onchange isready begin
        chart = Plot(scatter(x=1:10, y=rand(10)), Layout(title=attr(text="Live Chart")))
    end
end

@mounted WritableApp watchplots()
```

--------------------------------

### Define Heatmap Trace

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Create a heatmap trace with specified x, y, and z data, colorscale, and colorbar configuration. Suitable for visualizing matrix-like data.

```julia
heatmap_trace = PlotData(
    plot = PLOT_TYPE_HEATMAP,
    x = ["Mon", "Tue", "Wed", "Thu", "Fri"],
    y = ["Morning", "Afternoon", "Evening"],
    z = [[1,2,3,4,5], [6,7,8,9,10], [11,12,13,14,15]],
    colorscale = "Viridis",
    colorbar = ColorBar(title_text = "Intensity", ticksuffix = "", showticksuffix = "last")
)
```

--------------------------------

### Configure Line Styles for Traces

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Customize line styles for traces, including color, width, dash type, and shape. Supports various dash styles and spline smoothing for line plots.

```julia
using StipplePlotly

# Dashed spline line
line = PlotlyLine(
    color     = "rgb(220, 57, 18)",
    width     = 2,
    dash      = "dashdot",   # "solid" | "dot" | "dash" | "longdash" | "dashdot" | "longdashdot"
    shape     = "spline",    # "linear" | "spline" | "hv" | "vh" | "hvh" | "vhv"
    smoothing = 0.8,
    simplify  = true
)

trace = PlotData(
    x    = 1:20,
    y    = cumsum(randn(20)),
    mode = "lines",
    line = line,
    name = "Random Walk"
)
```

--------------------------------

### Configure Geographic Map Layout with PlotLayoutGeo

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Use PlotLayoutGeo to configure the base map for scattergeo and choropleth traces. Specify projection, scope, and visual properties like land and ocean colors.

```julia
using StipplePlotly

geo = PlotLayoutGeo(
    scope           = "north america",
    showland        = true,
    landcolor       = "#e8e8e8",
    showcoastlines  = true,
    coastlinecolor  = "#555",
    showocean       = true,
    oceancolor      = "#cce5ff",
    showcountries   = true,
    showlakes       = true,
    lakecolor       = "#cce5ff",
    resolution      = "50",
    geoprojection   = GeoProjection(type = "albers usa")
)

geo_trace = PlotData(
    plot          = PLOT_TYPE_SCATTERGEO,
    lat           = [40.71, 34.05, 41.88],
    lon           = [-74.01, -118.24, -87.63],
    text          = ["New York", "Los Angeles", "Chicago"],
    mode          = "markers+text",
    marker        = PlotDataMarker(size = 10, color = "crimson")
)

layout = PlotLayout(geo = geo)
```

--------------------------------

### Define Candlestick (OHLC) Trace

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Create a candlestick trace for financial data, including x-axis dates and open, high, low, close prices. Requires specific data arrays for each price point.

```julia
candle_trace = PlotData(
    plot = PLOT_TYPE_CANDLESTICK,
    x  = ["2024-01-01","2024-01-02","2024-01-03"],
    open  = [100.0, 102.0, 99.0],
    high  = [107.0, 108.0, 105.0],
    low   = [98.0,  100.0, 96.0],
    close = [105.0, 101.0, 103.0],
    name  = "AAPL"
)
```

--------------------------------

### `PlotLayoutGeo`

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Configures a geo-scoped base map for `scattergeo` and `choropleth` traces, including projection, scope, coastlines, land/ocean colors, and fit-bounds behaviour.

```APIDOC
## `PlotLayoutGeo` — Geographic map layout

Configures a geo-scoped base map for `scattergeo` and `choropleth` traces, including projection, scope, coastlines, land/ocean colors, and fit-bounds behaviour.

```julia
using StipplePlotly

geo = PlotLayoutGeo(
    scope           = "north america",
    showland        = true,
    landcolor       = "#e8e8e8",
    showcoastlines  = true,
    coastlinecolor  = "#555",
    showocean       = true,
    oceancolor      = "#cce5ff",
    showcountries   = true,
    showlakes       = true,
    lakecolor       = "#cce5ff",
    resolution      = "50",
    geoprojection   = GeoProjection(type = "albers usa")
)

geo_trace = PlotData(
    plot          = PLOT_TYPE_SCATTERGEO,
    lat           = [40.71, 34.05, 41.88],
    lon           = [-74.01, -118.24, -87.63],
    text          = ["New York", "Los Angeles", "Chicago"],
    mode          = "markers+text",
    marker        = PlotDataMarker(size = 10, color = "crimson")
)

layout = PlotLayout(geo = geo)
```
```

--------------------------------

### PlotLayoutMapbox

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Configuration for Mapbox map layouts.

```APIDOC
## PlotLayoutMapbox

### Description
Settings for integrating and configuring Mapbox maps within plots.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### Rendering Plots.jl Figures in Stipple

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Shows how to render figures created with the Plots.jl library within a Stipple application. The `Stipple.render()` function converts Plots.jl objects to PlotlyBase.Plot objects, enabling their display in the web interface.

```julia
using Stipple, Stipple.ReactiveTools, StipplePlotly, Plots, PlotlyBase

@app PlotsApp begin
    @out chart = Plot()

    @onchange isready begin
        # Build using familiar Plots.jl API
        p = Plots.plot(rand(30), title="Plots.jl via StipplePlotly", lw=2)
        Plots.scatter!(p, rand(15), ms=6)
        # render() converts it to PlotlyBase.Plot with normalised margins
        chart = Stipple.render(p)
    end
end

function ui()
    cell([plotly(:chart)])
end

@page("/", ui, model = PlotsApp)
```

--------------------------------

### Configure Error Bars with ErrorBar

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Add symmetric or asymmetric error bars to traces using the ErrorBar constructor. Supports data-based or percentage-based errors, with options for color, thickness, and visibility.

```julia
using StipplePlotly

# Symmetric data-based error bars
eb_sym = ErrorBar([0.5, 0.3, 0.7, 0.4])          # type="data", symmetric=true

# Asymmetric data-based error bars
eb_asym = ErrorBar([0.5, 0.3, 0.7], [0.2, 0.1, 0.4])  # symmetric=false

# Percentage-based error
eb_pct = ErrorBar(5.0)                             # type="percent", value=5.0

# Full manual construction
eb_full = ErrorBar(
    array     = [0.1, 0.2, 0.15],
    type      = "data",
    symmetric = true,
    color     = "red",
    thickness = 2,
    width     = 4,
    visible   = true
)

trace_with_errors = PlotData(
    x       = [1, 2, 3],
    y       = [4.0, 5.5, 3.8],
    mode    = "markers",
    error_y = eb_sym,
    error_x = eb_pct
)
```

--------------------------------

### `watchplots()`

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Forwards Plotly events to model fields. Generates the JavaScript snippet that registers event listeners on all sync-enabled plots in the current view and routes events to reactive model fields. Call it from `js_mounted` (or the `@mounted` macro). Plots must carry a class `sync_<prefix>` (set automatically by `plot(..., syncevents=true)` or `plot(..., syncprefix="...")`) so the listener knows which fields to update.

```APIDOC
## `watchplots()` — Forward Plotly events to model fields

Generates the JavaScript snippet that registers event listeners on all sync-enabled plots in the current view and routes events to reactive model fields. Call it from `js_mounted` (or the `@mounted` macro). Plots must carry a class `sync_<prefix>` (set automatically by `plot(..., syncevents=true)` or `plot(..., syncprefix="...")`) so the listener knows which fields to update.

```julia
using Stipple, Stipple.ReactiveTools, StipplePlotly, PlotlyBase

@app SalesApp begin
    @mixin revenue_chart::PBPlotWithEvents
    # expands to:
    #   revenue_chart        ::R{Plot}
    #   revenue_chart_selected ::R{Dict{String,Any}}
    #   revenue_chart_hover    ::R{Dict{String,Any}}
    #   revenue_chart_click    ::R{Dict{String,Any}}
    #   revenue_chart_relayout ::R{Dict{String,Any}}

    @onchange isready begin
        isready || return
        revenue_chart.data   = [scatter(y = rand(50), name = "Revenue")]
        revenue_chart.layout = Layout(title = attr(text = "Live Sales"))
    end

    @onchange revenue_chart_selected begin
        haskey(revenue_chart_selected, "points") || return
        pts = getindex.(revenue_chart_selected["points"], "pointIndex")
        @info "User selected points: $pts"
    end

    @onchange revenue_chart_hover begin
        isempty(revenue_chart_hover) && return
        pt = revenue_chart_hover["points"][1]
        @info "Hover: x=$(pt["x"]), y=$(pt["y"])"
    end
end

@mounted SalesApp watchplots()

function ui()
    cell([
        plotly(:revenue_chart, syncevents = true, keepselection = false)
    ])
end

@page("/", ui, model = SalesApp)
```
```

--------------------------------

### Define 3-D Surface Trace

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Create a 3-D surface trace using z-axis data and a specified colorscale. Ideal for visualizing functions of two variables.

```julia
surface_trace = PlotData(
    plot = PLOT_TYPE_SURFACE,
    z = [[0.0,1.0,2.0],[1.0,2.0,3.0],[2.0,3.0,4.0]],
    colorscale = "Blues"
)
```

--------------------------------

### PlotLayoutTitle

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Configuration for the plot title.

```APIDOC
## PlotLayoutTitle

### Description
Specifies the text, font, and positioning of the main plot title.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### PlotLayout

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

The main layout object for configuring plot aesthetics.

```APIDOC
## PlotLayout

### Description
The primary object for defining the overall layout and appearance of a plot.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### PlotLayoutGeo

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Configuration for geographic map layouts.

```APIDOC
## PlotLayoutGeo

### Description
Settings specific to geographic map layouts, including projection and center.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### Configure Axes with PlotLayoutAxis

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Customize individual x or y axes using PlotLayoutAxis. Supports log scales, date types, custom ticks, gridlines, ranges, and overlaying multiple axes.

```julia
using StipplePlotly

# Log-scale y-axis with custom ticks
y_log = PlotLayoutAxis(
    xy          = "y",
    index       = 1,
    type        = "log",
    title_text  = "Count (log scale)",
    showgrid    = true,
    gridcolor   = "#ddd",
    zeroline    = false,
    tickformat  = ".1e",
    range       = [0, 6]
)

# Date x-axis with period ticks
x_date = PlotLayoutAxis(
    xy           = "x",
    index        = 1,
    type         = "date",
    title_text   = "Date",
    ticklabelmode = "period",
    dtick        = "M1",
    tickformat   = "%b %Y",
    tickangle    = -30
)

# Overlay a second y-axis on the right
y2 = PlotLayoutAxis(
    xy         = "y",
    index      = 2,
    overlaying = "y",
    side       = "right",
    title_text = "Price (USD)",
    showgrid   = false
)

layout = PlotLayout(
    xaxis = [x_date],
    yaxis = [y_log, y2]
)
```

--------------------------------

### Forward Plotly Events to Model Fields with watchplots()

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Use watchplots() in js_mounted to route events from sync-enabled plots to reactive model fields. Plots must have a 'sync_<prefix>' class, automatically set by syncevents=true or syncprefix.

```julia
using Stipple, Stipple.ReactiveTools, StipplePlotly, PlotlyBase

@app SalesApp begin
    @mixin revenue_chart::PBPlotWithEvents
    # expands to:
    #   revenue_chart        ::R{Plot}
    #   revenue_chart_selected ::R{Dict{String,Any}}
    #   revenue_chart_hover    ::R{Dict{String,Any}}
    #   revenue_chart_click    ::R{Dict{String,Any}}
    #   revenue_chart_relayout ::R{Dict{String,Any}}

    @onchange isready begin
        isready || return
        revenue_chart.data   = [scatter(y = rand(50), name = "Revenue")]
        revenue_chart.layout = Layout(title = attr(text = "Live Sales"))
    end

    @onchange revenue_chart_selected begin
        haskey(revenue_chart_selected, "points") || return
        pts = getindex.(revenue_chart_selected["points"], "pointIndex")
        @info "User selected points: $pts"
    end

    @onchange revenue_chart_hover begin
        isempty(revenue_chart_hover) && return
        pt = revenue_chart_hover["points"][1]
        @info "Hover: x=$(pt["x"]), y=$(pt["y"])"
    end
end

@mounted SalesApp watchplots()

function ui()
    cell([
        plotly(:revenue_chart, syncevents = true, keepselection = false)
    ])
end

@page("/", ui, model = SalesApp)
```

--------------------------------

### PlotLayoutAxis

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Configuration for plot axes.

```APIDOC
## PlotLayoutAxis

### Description
Defines properties for the x and y axes of a plot, such as titles, ranges, and tick configurations.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### Configure Scatter Marker Styles

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Define marker styles for scatter plots, including size, color mapping, color scales, and outlines. Useful for creating bubble charts or data-rich scatter plots.

```julia
using StipplePlotly

# Color-mapped bubbles
marker = PlotDataMarker(
    size  = [10, 20, 30, 15, 25],
    color = [1.0, 2.5, 4.0, 3.2, 0.8],   # mapped to colorscale
    cmin  = 0.0,
    cmax  = 5.0,
    colorscale  = "Viridis",
    showscale   = true,
    colorbar    = ColorBar(
        title_text = "Score",
        ticksuffix = " pts",
        showticksuffix = "last"
    ),
    line = PlotlyLine(color = "black", width = 1),
    opacity = 0.85
)

bubble_trace = PlotData(
    x      = [1, 2, 3, 4, 5],
    y      = [5, 3, 8, 1, 7],
    mode   = "markers",
    marker = marker,
    name   = "Bubble Chart"
)
```

--------------------------------

### `plotdata()`

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Builds grouped traces from a DataFrame. Convenience function that splits a `DataFrames.DataFrame` by a grouping column and returns a `Vector{PlotData}`, one trace per group. Supports optional text labels and accepts any `PlotData` keyword argument via `kwargs`.

```APIDOC
## `plotdata()` — Build grouped traces from a DataFrame

Convenience function that splits a `DataFrames.DataFrame` by a grouping column and returns a `Vector{PlotData}`, one trace per group. Supports optional text labels and accepts any `PlotData` keyword argument via `kwargs`.

```julia
using StipplePlotly, DataFrames

df = DataFrame(
    quarter  = repeat(["Q1","Q2","Q3","Q4"], 3),
    revenue  = [120, 185, 162, 210, 95, 145, 130, 178, 80, 110, 95, 140],
    region   = repeat(["North","South","East"], inner=4),
    label    = ["OK","High","OK","High","Low","OK","OK","High","Low","Low","OK","OK"]
)

traces = plotdata(df, :quarter, :revenue;
    groupfeature = :region,
    text         = df.label,
    mode         = "lines+markers",
    plottype     = PLOT_TYPE_SCATTER
)
# Returns 3 PlotData traces (North, South, East), each with x=quarters, y=revenues

# Use in a reactive app
using Stipple, Stipple.ReactiveTools

@app RegionalDashboard begin
    @out plots = plotdata(df, :quarter, :revenue; groupfeature = :region, mode = "markers")

    @onchange isready begin
        plots = plotdata(df, :quarter, :revenue; groupfeature = :region, mode = "markers")
    end
end

function ui()
    cell([plot("plots")])
end

@page("/dashboard", ui, model = RegionalDashboard)
```
```

--------------------------------

### PlotLayoutLegend

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Configuration for the plot legend.

```APIDOC
## PlotLayoutLegend

### Description
Defines the position, orientation, and appearance of the plot legend.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### Read-Only Plotly Chart

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Defines a Stipple app with a read-only Plotly chart using `PBPlotWithEventsReadOnly`. The server exclusively owns the plot data, preventing client-side mutations. The chart is initialized upon app readiness.

```julia
using Stipple, Stipple.ReactiveTools, StipplePlotly, PlotlyBase

# Read-only plot: only the server can push new chart data
@app ReadOnlyApp begin
    @mixin snapshot::PBPlotWithEventsReadOnly

    @onchange isready begin
        snapshot = Plot(bar(x=["A","B","C"], y=[3,1,4]))
    end
end

@mounted ReadOnlyApp watchplots()
```

--------------------------------

### plot

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/charts.md

Generates a plot using the provided data and configuration. This is the primary function for creating visualizations.

```APIDOC
## plot

### Description
Generates a plot using the provided data and configuration.

### Method
`plot(data::PlotData, config::PlotConfig)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```julia
plot(my_data, my_config)
```

### Response
#### Success Response (plot object)
- **plot_object** (Plot) - The generated plot object.

#### Response Example
```julia
# A plot object is returned, specific type depends on the plotting backend.
```
```

--------------------------------

### Configure ColorBar for Heatmaps

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Use ColorBar to control the appearance and position of a color scale legend attached to traces with continuous color axes. Customize title, ticks, size, and position.

```julia
using StipplePlotly

cb = ColorBar(
    title_text = "Temperature (°C)",
    title_side = "right",
    title_font = Font(size = 13, color = "#555"),
    ticksuffix = "°",
    showticksuffix = "last",
    thickness  = 20,
    len        = 0.75,
    x          = 1.02,
    xanchor    = "left",
    ticks      = "outside",
    ticklen    = 5,
    tickwidth  = 1,
    tickcolor  = "#444",
    borderwidth = 1,
    bordercolor = "#ccc"
)

heatmap = PlotData(
    plot       = PLOT_TYPE_HEATMAP,
    z          = [[1,2,3],[4,5,6],[7,8,9]],
    colorscale = "RdBu",
    colorbar   = cb
)
```

--------------------------------

### ErrorBar

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Configures error bars for traces, supporting symmetric or asymmetric error bars from data arrays or percentage values.

```APIDOC
## `ErrorBar` — Error bar configuration

Convenience constructors make it easy to add symmetric or asymmetric error bars from data arrays or percentage values.

```julia
using StipplePlotly

# Symmetric data-based error bars
eb_sym = ErrorBar([0.5, 0.3, 0.7, 0.4])          # type="data", symmetric=true

# Asymmetric data-based error bars
eb_asym = ErrorBar([0.5, 0.3, 0.7], [0.2, 0.1, 0.4])  # symmetric=false

# Percentage-based error
eb_pct = ErrorBar(5.0)                             # type="percent", value=5.0

# Full manual construction
eb_full = ErrorBar(
    array     = [0.1, 0.2, 0.15],
    type      = "data",
    symmetric = true,
    color     = "red",
    thickness = 2,
    width     = 4,
    visible   = true
)

trace_with_errors = PlotData(
    x       = [1, 2, 3],
    y       = [4.0, 5.5, 3.8],
    mode    = "markers",
    error_y = eb_sym,
    error_x = eb_pct
)
```
```

--------------------------------

### PlotDataMarker

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/charts.md

Marker configuration for data points within a plot trace.

```APIDOC
## PlotDataMarker

### Description
Defines the style and appearance of individual data points (markers) within a plot trace, such as symbol, size, and color.

### Type Definition
```julia
struct PlotDataMarker
    symbol::String
    size::Int
    color::String
    # ... other marker fields
end
```

### Usage
Use `PlotDataMarker` to customize the appearance of points in a `Trace`.
```

--------------------------------

### Define Multi-subplot Grid with PlotLayoutGrid

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Create multi-subplot layouts using PlotLayoutGrid. Define the grid dimensions and pattern (e.g., 'independent') to arrange plots and assign traces to specific subplots using axis indices.

```julia
using StipplePlotly

# 2 rows × 3 columns of independent subplots
grid = PlotLayoutGrid(
    rows      = 2,
    columns   = 3,
    pattern   = "independent",
    roworder  = "top to bottom",
    xgap      = 0.08,
    ygap      = 0.12
)

layout = PlotLayout(
    grid  = grid,
    xaxis = [PlotLayoutAxis(xy="x", index=i, title_text="X$i") for i in 1:3],
    yaxis = [PlotLayoutAxis(xy="y", index=i, title_text="Y$i") for i in 1:2]
)

# Assign traces to specific subplots via xaxis/yaxis fields
trace1 = PlotData(x=[1,2,3], y=[4,5,6], xaxis="x1", yaxis="y1", name="Top-Left")
trace2 = PlotData(x=[1,2,3], y=[7,8,9], xaxis="x2", yaxis="y1", name="Top-Mid")
```

--------------------------------

### ColorBar

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Configures the color bar legend for traces with continuous color axes, controlling its position, size, tick formatting, title, and border.

```APIDOC
## `ColorBar` — Color scale legend

Attached to traces or markers with continuous color axes. Controls position, size, tick formatting, title, and border.

```julia
using StipplePlotly

cb = ColorBar(
    title_text = "Temperature (°C)",
    title_side = "right",
    title_font = Font(size = 13, color = "#555"),
    ticksuffix = "°",
    showticksuffix = "last",
    thickness  = 20,
    len        = 0.75,
    x          = 1.02,
    xanchor    = "left",
    ticks      = "outside",
    ticklen    = 5,
    tickwidth  = 1,
    tickcolor  = "#444",
    borderwidth = 1,
    bordercolor = "#ccc"
)

heatmap = PlotData(
    plot       = PLOT_TYPE_HEATMAP,
    z          = [[1,2,3],[4,5,6],[7,8,9]],
    colorscale = "RdBu",
    colorbar   = cb
)
```
```

--------------------------------

### Build Grouped Traces from DataFrame with plotdata()

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Use plotdata() to split a DataFrame by a grouping column, creating a Vector{PlotData} with one trace per group. Supports optional text labels and accepts PlotData keyword arguments.

```julia
using StipplePlotly, DataFrames

df = DataFrame(
    quarter  = repeat(["Q1","Q2","Q3","Q4"], 3),
    revenue  = [120, 185, 162, 210, 95, 145, 130, 178, 80, 110, 95, 140],
    region   = repeat(["North","South","East"], inner=4),
    label    = ["OK","High","OK","High","Low","OK","OK","High","Low","Low","OK","OK"]
)

traces = plotdata(df, :quarter, :revenue;
    groupfeature = :region,
    text         = df.label,
    mode         = "lines+markers",
    plottype     = PLOT_TYPE_SCATTER
)
# Returns 3 PlotData traces (North, South, East), each with x=quarters, y=revenues

# Use in a reactive app
using Stipple, Stipple.ReactiveTools

@app RegionalDashboard begin
    @out plots = plotdata(df, :quarter, :revenue; groupfeature = :region, mode = "markers")

    @onchange isready begin
        plots = plotdata(df, :quarter, :revenue; groupfeature = :region, mode = "markers")
    end
end

function ui()
    cell([plot("plots")])
end

@page("/dashboard", ui, model = RegionalDashboard)
```

--------------------------------

### PlotConfig

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/charts.md

Configuration object for customizing plot appearance and behavior.

```APIDOC
## PlotConfig

### Description
Represents the configuration settings for a plot, allowing customization of various aspects like titles, axes, and layout.

### Type Definition
```julia
struct PlotConfig
    title::String
    xaxis_title::String
    yaxis_title::String
    # ... other configuration fields
end
```

### Usage
Instantiate `PlotConfig` to define how your plot should look.
```

--------------------------------

### Define Scatter/Line Trace with PlotData

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Defines a single Plotly trace for scatter or line plots. Customize appearance with `PlotlyLine` and `PlotDataMarker`.

```julia
using StipplePlotly

# Scatter / line trace
scatter_trace = PlotData(
    x = [1, 2, 3, 4, 5],
    y = [2.1, 3.8, 2.5, 4.9, 3.2],
    mode = "lines+markers",
    name = "Series A",
    line = PlotlyLine(color = "#1f77b4", width = 2, dash = "solid"),
    marker = PlotDataMarker(size = 8, symbol = "circle")
)
```

--------------------------------

### Render Plotly Plot Element with plot()

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Generates the HTML `<plotly>` Vue component. Use `plot()` to bind data, layout, and configuration to a model field. Enable `syncevents` to forward Plotly events to Julia handlers.

```julia
using Stipple, Stipple.ReactiveTools, StipplePlotly

# Minimal scatter plot bound to model field `myplot`
plot("myplot.data")
```

```julia
layout = PlotLayout(
    title = PlotLayoutTitle(text = "Sales by Quarter"),
    xaxis = [PlotLayoutAxis(xy = "x", title_text = "Quarter")],
    yaxis = [PlotLayoutAxis(xy = "y", title_text = "Revenue (USD)")]
)
plot("myplot.data"; layout)
```

```julia
# Enable event forwarding: maps plotly_selected → model.myplot_selected, etc.
plot("myplot.data"; syncevents = true)
```

```julia
# Explicit sync prefix (e.g. two plots on same page)
plot("chart1.data"; syncprefix = "revenue_chart")
```

```julia
# With PlotlyBase.Plot field via convenience wrapper
plotly(:myplot)
```

```julia
# Shared config across multiple plots
plotly(:plot1, config = :shared_config)
plotly(:plot2, config = :shared_config)
```

--------------------------------

### PlotlyLine

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/charts.md

Configuration for the line style in a plot trace.

```APIDOC
## PlotlyLine

### Description
Specifies the visual properties of a line in a plot trace, including its color, width, and dash style.

### Type Definition
```julia
struct PlotlyLine
    color::String
    width::Int
    dash::String
    # ... other line fields
end
```

### Usage
Configure line appearance using `PlotlyLine` within a `Trace`.
```

--------------------------------

### MCenter

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Represents the center point for map-related layouts.

```APIDOC
## MCenter

### Description
Defines the center coordinates for geographic plots.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### PlotLayoutGrid

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Configuration for grid lines within plot axes.

```APIDOC
## PlotLayoutGrid

### Description
Controls the appearance and visibility of grid lines on plot axes.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### `plotly()` — Symbol-based plot shorthand

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

A convenience wrapper around `plot()` for use with `PlotlyBase.Plot`-typed model fields. It automatically derives the `.data`, `.layout`, and `.config` sub-fields from a single symbol, allowing for optional overrides.

```APIDOC
## `plotly()` — Symbol-based plot shorthand

A convenience wrapper around `plot()` for use with `PlotlyBase.Plot`-typed model fields. Derives the `.data`, `.layout`, and `.config` sub-fields automatically from a single symbol, supporting an optional override for each.

### Method

`plotly(field_symbol; data = "data", layout = "layout", config = "config", syncevents = false, syncprefix = "sync_")`

### Parameters

- **field_symbol** (Symbol) - Required - The symbol referencing the `PlotlyBase.Plot` typed model field.
- **data** (String) - Optional - The name of the data sub-field (defaults to "data").
- **layout** (String) - Optional - The name of the layout sub-field (defaults to "layout").
- **config** (String) - Optional - The name of the config sub-field (defaults to "config").
- **syncevents** (Bool) - Optional - If true, enables forwarding of Plotly events to Julia handlers.
- **syncprefix** (String) - Optional - A prefix for event synchronization.

### Request Example

```julia
using Stipple, Stipple.ReactiveTools, StipplePlotly, PlotlyBase

@app MyDashboard begin
    @mixin chart::PBPlotWithEvents  # adds chart, chart_selected, chart_hover, chart_click, chart_relayout
end

function ui()
    cell([
        # Renders <plotly :data="chart.data" :layout="chart.layout" :config="chart.config">
        plotly(:chart, syncevents = true),

        # Override config reference only
        plotly(:chart, config = :global_config),
    ])
end

@mounted MyDashboard watchplots()
@page("/", ui, model = MyDashboard)
```

### Response

Returns an HTML string representing the `<plotly>` Vue component.
```

--------------------------------

### PlotLayoutAxis

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Configures individual axes (x or y) for plots, including type, scale, titles, gridlines, tick formatting, and range.

```APIDOC
## `PlotLayoutAxis` — Axis configuration

Configures a single x or y axis (identified by `xy = "x"` or `"y"` and `index`). Supports tick formatting, gridlines, range control, scale linking, spike lines, and multi-axis subplot setups.

```julia
using StipplePlotly

# Log-scale y-axis with custom ticks
y_log = PlotLayoutAxis(
    xy          = "y",
    index       = 1,
    type        = "log",
    title_text  = "Count (log scale)",
    showgrid    = true,
    gridcolor   = "#ddd",
    zeroline    = false,
    tickformat  = ".1e",
    range       = [0, 6]
)

# Date x-axis with period ticks
x_date = PlotLayoutAxis(
    xy           = "x",
    index        = 1,
    type         = "date",
    title_text   = "Date",
    ticklabelmode = "period",
    dtick        = "M1",
    tickformat   = "%b %Y",
    tickangle    = -30
)

# Overlay a second y-axis on the right
y2 = PlotLayoutAxis(
    xy         = "y",
    index      = 2,
    overlaying = "y",
    side       = "right",
    title_text = "Price (USD)",
    showgrid   = false
)

layout = PlotLayout(
    xaxis = [x_date],
    yaxis = [y_log, y2]
)
```
```

--------------------------------

### Trace

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/charts.md

Represents a single data series (trace) to be plotted, including its data, type, and styling.

```APIDOC
## Trace

### Description
A `Trace` object defines a single series of data to be visualized in a plot. It can be configured as a line, scatter plot, bar chart, etc., with associated styling for lines and markers.

### Type Definition
```julia
struct Trace
    x::Vector{<:Number}
    y::Vector{<:Number}
    type::String # e.g., "scatter", "bar"
    mode::String # e.g., "lines", "markers", "lines+markers"
    name::String
    line::PlotlyLine
    marker::PlotDataMarker
    # ... other trace fields
end
```

### Usage
Create one or more `Trace` objects and combine them into a `PlotData` structure for plotting.
```

--------------------------------

### PlotAnnotation

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Configuration for adding annotations to plots.

```APIDOC
## PlotAnnotation

### Description
Allows for the addition of text or shapes as annotations on the plot.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### PRotation

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Represents rotation properties for plot elements.

```APIDOC
## PRotation

### Description
Defines rotation angles for various plot components.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### PlotData

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/charts.md

Data structure for holding the information required to generate a plot, including traces and markers.

```APIDOC
## PlotData

### Description
Encapsulates the data for a plot, typically consisting of one or more traces. It defines the series to be plotted.

### Type Definition
```julia
struct PlotData
    traces::Vector{Trace}
    # ... other data fields
end
```

### Usage
Create `PlotData` by populating it with `Trace` objects.
```

--------------------------------

### Symbol-based Plot Shorthand with plotly()

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

A convenience wrapper for `plot()` when using `PlotlyBase.Plot`-typed model fields. It automatically derives `.data`, `.layout`, and `.config` sub-fields from a symbol, allowing optional overrides.

```julia
using Stipple, Stipple.ReactiveTools, StipplePlotly, PlotlyBase

@app MyDashboard begin
    @mixin chart::PBPlotWithEvents  # adds chart, chart_selected, chart_hover, chart_click, chart_relayout
end

function ui()
    cell([
        # Renders <plotly :data="chart.data" :layout="chart.layout" :config="chart.config">
        plotly(:chart, syncevents = true),

        # Override config reference only
        plotly(:chart, config = :global_config),
    ])
end

@mounted MyDashboard watchplots()
@page("/", ui, model = MyDashboard)
```

--------------------------------

### ColorBar

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Represents the color bar configuration for plots.

```APIDOC
## ColorBar

### Description
Configuration for the color bar, including its appearance and behavior.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### Define Bar Chart Trace with PlotData

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Defines a single Plotly trace for bar charts using `PLOT_TYPE_BAR`. Customize marker appearance and text labels.

```julia
using StipplePlotly

# Bar chart trace
bar_trace = PlotData(
    plot = PLOT_TYPE_BAR,
    x = ["Q1", "Q2", "Q3", "Q4"],
    y = [120_000, 185_000, 162_000, 210_000],
    name = "Revenue",
    marker = PlotDataMarker(color = "#2ca02c"),
    text = ["120K", "185K", "162K", "210K"],
    textposition = "outside"
)
```

--------------------------------

### Font

Source: https://github.com/genieframework/stippleplotly.jl/blob/main/docs/src/API/layouts.md

Defines font properties for various plot elements.

```APIDOC
## Font

### Description
Specifies font properties such as family, size, and color.

### Parameters
(No specific parameters documented in the source)
```

--------------------------------

### Configure Plot Layout

Source: https://context7.com/genieframework/stippleplotly.jl/llms.txt

Define the overall layout for a Plotly chart, including titles, axes, legends, margins, and background colors. Supports complex configurations like subplots.

```julia
using StipplePlotly

layout = PlotLayout(
    title = PlotLayoutTitle(
        text = "Monthly Sales Dashboard",
        font = Font(family = "Arial", size = 20, color = "#333"),
        x = 0.5,
        xanchor = "center"
    ),
    xaxis = [PlotLayoutAxis(
        xy = "x",
        index = 1,
        title_text = "Month",
        tickangle = -45,
        showgrid = true,
        gridcolor = "#eee"
    )],
    yaxis = [PlotLayoutAxis(
        xy = "y",
        index = 1,
        title_text = "USD",
        rangemode = "tozero",
        tickprefix = "$"
    )],
    legend = PlotLayoutLegend(
        orientation = "h",
        x = 0.0,
        y = -0.2,
        xanchor = "left"
    ),
    margin_l = 60, margin_r = 30, margin_t = 80, margin_b = 60,
    plot_bgcolor = "#fafafa",
    paper_bgcolor = "#ffffff",
    barmode = "group",
    hovermode = "x unified"
)
```

```julia
# Subplot layout with a 2×2 grid
grid_layout = PlotLayout(
    grid = PlotLayoutGrid(rows = 2, columns = 2, pattern = "independent"),
    xaxis = [
        PlotLayoutAxis(xy = "x", index = 1, title_text = "X1"),
        PlotLayoutAxis(xy = "x", index = 2, title_text = "X2"),
    ],
    yaxis = [
        PlotLayoutAxis(xy = "y", index = 1, title_text = "Y1"),
        PlotLayoutAxis(xy = "y", index = 2, title_text = "Y2"),
    ]
)
```