import colight.plot as Plot
from colight.plot import md

State

State in Colight is used when: - Data is used in more than one place, or - Data changes over time (via user interaction or from Python)

It provides: - Deduplication (during serialization) - Efficient change propagation between Python and JavaScript - Reactive UI updates within JavaScript

State API

Minimal example

import colight.plot as Plot

(
    Plot.State({"clicks": 0})
    | [
        "div.bg-yellow-200.p-4",
        {"onClick": Plot.js("(e) => $state.clicks = ($state.clicks || 0) + 1")},
        Plot.js("`Clicked ${$state.clicks} times`"),
    ]
    | [
        "div.p-3.border.text-center",
        {"onClick": Plot.js("(e) => $state.update({clicks: 0})")},
        "Reset",
    ]
)

State Updates

State updates in Colight work bidirectionally between Python and JavaScript:

Python → JavaScript Updates

When you update state from Python using widget.state.update() or by setting attributes directly:

1. The update is normalized into a list of [key, operation, payload] tuples
2. For synced state, the update is applied locally to widget.state
3. The update is serialized to JSON and sent to JavaScript via widget messaging
4. Any registered Python listeners are notified

JavaScript → Python Updates

When state is updated from JavaScript using $state.update():

1. The update is normalized into [key, operation, payload] format
2. The update is applied locally to the JavaScript state store
3. For synced state keys, the update is sent back to Python
4. Python applies the update and notifies any listeners

Update Operations

Updates support different operations beyond just setting values:

• append: Add item to end of list
• concat: Join two lists together
• setAt: Set value at specific index
• reset: Reset value to initial state