wind dynamic.instructions.md

Dynamic JSON renderer (lib/src/dynamic/)

WDynamic renders Flutter widget trees from JSON. Pieces:

• WDynamic — the StatefulWidget consumers use. Composes the other parts.
• WDynamicConfig — security + customization (denyWidgets, builders, customIcons, maxDepth, callbacks).
• WDynamicState — id-keyed value store + listeners (ChangeNotifier).
• WDynamicController — wraps external state; tracks _ownsState to gate disposal.
• WActionHandler — bridges JSON actions to Dart callbacks; handles _value injection.
• WDynamicRenderer — the dispatch loop; one giant switch over type strings.

JSON schema

{
  "type": "WText",
  "props": {
    "text": "Hello",
    "className": "text-lg",
    "id": "greeting",
    "onTap": {"action": "navigate", "args": {"route": "/home"}}
  },
  "children": [...]
}

• type (String, REQUIRED) — must be in the whitelist (defaultWindWidgets ∪ defaultFlutterWidgets ∪ config.builders.keys) and not in denyWidgets.
• props (Map, optional) — widget-specific. className, id, action props, and per-widget config live here.
• children (List, optional) — nested widget definitions.

Security model (whitelist first)

Order of resolution in WDynamicConfig.isAllowed(type):

1. config.builders[type] — custom builder always wins.
2. config.denyWidgets.contains(type) — explicit block; emits error widget.
3. Default whitelist (13 Wind widgets + 16 Flutter core).

Untrusted JSON: pass denyWidgets for surfaces a remote source must not invoke (e.g., 'Container' if you don't trust raw boxes). Always set maxDepth (default 50) — recursion bomb mitigation.

State binding (id-keyed widgets)

WInput, WCheckbox, WSelect, WDatePicker with props.id read initial value from state.get(id) and write back on change. Reactive: same id from another widget triggers a rebuild via WDynamicState's addIdListener.

External vs internal state ownership:

• WDynamic(controller: WDynamicController()) — _ownsState = false; the host owns disposal.
• WDynamic(...) no controller — _ownsState = true; WDynamic creates the state and disposes it.