kui-lua 0.1.0-alpha.39

Lua extensions for kui via mlua: table trees in, events as tables out
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

# kui-lua

Lua scripts as kui extensions: a script returns its view as a table tree and gets events back as tables.

`kui-lua` loads a Lua script as an extension a kui host can place in its frame. The script defines `view(env, slot)`, which returns a plain table built with the injected `row` / `column` / `text` / `button` prelude, and optionally `on_event(ev)`, which hears the events the script's own nodes emit and may return replies for the host. Only data crosses the boundary: no closure lives on either side. Use it when a Rust app on kui wants scriptable panels or plugins.

## Install

```
cargo add kui-lua kui-native
```

## Example

The Rust host reserves a position for the script under a namespace and hears its replies:

```rust
use kui_lua::LuaExtension;
use kui_native::{App, NodeSpec, Ui, UiEvent, Value};

struct Host { toggles: u32 }

impl App for Host {
    fn view(&mut self, ui: &mut Ui<'_>) {
        ui.configure_root(NodeSpec::row().fill().pad(16.0).gap(16.0));
        ui.slot_with(
            "todos/panel",
            &Value::map([
                ("title", "todos".into()),
                ("on_toggle", Value::map([("kind", "toggled".into())])),
            ]),
        );
    }

    fn on_event(&mut self, ev: UiEvent) {
        if ev.kind() == Some("toggled") {
            self.toggles += 1;
        }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let script = LuaExtension::from_file("panel.lua")?;
    kui_native::app("todos").extension_as("todos", script).run(Host { toggles: 0 })
}
```

`panel.lua` fills the `panel` slot, reads the host's params and replies with the host's template:

```lua
slots = { "panel" }

local done = {}
local on_toggle

function view(env, slot)
  local t = env.theme
  on_toggle = slot.params.on_toggle
  return column {
    width = 300, pad = 16, gap = 10, bg = t.surface, radius = 10,
    text(slot.params.title, { size = 12, color = t.muted }),
    row { on_click = { kind = "toggle", index = 1 },
          text((done[1] and "[x] " or "[ ] ") .. "wire up wgpu") },
  }
end

function on_event(ev)
  if ev.kind == "toggle" then
    done[ev.index] = not done[ev.index]
    local reply = { index = ev.index }
    for k, v in pairs(on_toggle) do reply[k] = v end
    return reply
  end
end
```

The crate docs list everything a script gets: the builders, the `env` facts and functions, the `slot` argument, the props shapes, and `kui_lua::luals_meta()` for editor completion.

## Where it fits

| Crate | Role |
| --- | --- |
| [kui-core](https://crates.io/crates/kui-core) | The model and layout |
| [kui-wgpu](https://crates.io/crates/kui-wgpu) | The renderer |
| [kui-native](https://crates.io/crates/kui-native) | The windowed runner most apps use |
| [kui-derive](https://crates.io/crates/kui-derive) | `#[derive(Message)]` |
| [kui-ffi](https://crates.io/crates/kui-ffi) | The C API and plugin loader |
| kui-lua | Lua scripts as extensions (this crate) |
| [@qxuken/kui](https://www.npmjs.com/package/@qxuken/kui) | The Node.js package |

## Documentation

- API: <https://docs.rs/kui-lua>
- Book: <https://kui-book.qxuken.dev>
- Repository: <https://github.com/qxuken/kui>

## License

MIT