lumen_ir/
addon.rs

1//! A browser add-on, as a compiled app carries it.
2//!
3//! An add-on is a package of files the browser loads beside the runtime: a
4//! JavaScript module, and optionally stylesheets and a script that runs before
5//! the page paints. What travels in the artifact is the part every target
6//! needs to agree on, the functions it offers scripts and the elements it
7//! answers for, so a compile, a build-time render and a desktop run all read
8//! one description of it. The files themselves are the site's, and the site
9//! manifest names them.
10//!
11//! Types are kept as the text the add-on's descriptor wrote (`int`,
12//! `string[]`, `{string: any}`): this crate sits below the script layer that
13//! reads them, and the spelling is the one a candela declaration uses anyway.
14
15use serde::{Deserialize, Serialize};
16
17/// One add-on an app depends on.
18#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
19pub struct Addon {
20    /// The name the app declared it under in `[dependencies]`.
21    pub name: String,
22    /// The script namespace its functions live in: `echo` makes a function
23    /// `echo::shout` in candela.
24    pub namespace: String,
25    /// The functions it offers scripts, in the order its descriptor lists
26    /// them.
27    pub functions: Vec<AddonFunction>,
28    /// The markup elements it answers for.
29    pub elements: Vec<AddonElement>,
30}
31
32/// One function an add-on offers scripts.
33#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
34pub struct AddonFunction {
35    /// The name a script calls it by, and the name of the module export that
36    /// answers.
37    pub name: String,
38    /// Its parameters, in order.
39    pub params: Vec<AddonParam>,
40    /// What it returns, as a type spelling. `null` for nothing, and always
41    /// `null` for an asynchronous function, whose result arrives as an event.
42    pub returns: String,
43    /// The event an asynchronous function's result arrives as, or `None` for
44    /// a function that answers before it returns.
45    ///
46    /// A script calls an asynchronous function with a tag after its declared
47    /// arguments. When the module's promise settles, the script's `<event>`
48    /// handler is called with the tag and the value, or `<event>_error` with
49    /// the tag and the reason.
50    pub event: Option<String>,
51    /// One line describing it, for editor tooling.
52    pub doc: String,
53}
54
55/// One declared parameter.
56#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
57pub struct AddonParam {
58    /// Its name, for docs and error messages.
59    pub name: String,
60    /// Its type, as a type spelling.
61    pub ty: String,
62}
63
64/// One markup element an add-on answers for.
65///
66/// The page writes it as the HTML element named here, with whatever the
67/// markup put inside it as the content a visitor sees until the add-on takes
68/// the element over, and on every target where it never does.
69#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
70pub struct AddonElement {
71    /// The markup tag, such as `echo-view`.
72    pub tag: String,
73    /// The HTML element it is written as, such as `div` or `canvas`.
74    pub html: String,
75    /// True when that element takes no children and no end tag.
76    pub void: bool,
77}
lumen_ir/addon.rs

lumen_ir/
addon.rs
