notesy::view

What a panel, a tab or a sidebar section shows is a view: plain values naming notesy's own widgets, which notesy draws. A script never draws; it describes, and a plugin's UI always looks like notesy, in any theme.

A view is a tree of parts. Each builder below returns an object (#{ kind: "row", icon: "check", text: "Call Ana" }); set any of its other fields after, like row.target = "call". A list is a column; plain text is a note.

rustuse notesy::{view, Color, Icon};

fn build(note) {
    let row = view::row(Icon::ArrowRight, "Record the demo video");
    row.target = "video";
    row.color = Color::Accent;
    view::column([
        view::header(Icon::Check, "Tasks", "3 left in this note"),
        view::stats([["3", "to do"], ["2", "done"]]),
        view::progress(2, 5),
        view::caption("to do"),
        row,
    ])
}

#Parts

Icons, colors and tones are enums of notesy's names (Names: Icon, Color, Tone, Side, Method, Command, Zone, Event): Icon::Check, Color::Accent, Tone::Primary. Its own icons are by their names: the plugin's own [[icons]] (plugin.toml), notesy's (check, clock, file, folder, link, tag, calendar, bulb, alert, info, arrow-right, arrow-up, pin, plugin, canvas …), or another plugin's as <plugin id>.<name>. Colors are a theme color's key (accent, success, warning, danger, text_muted …), one of the plugin's own [[colors]], or #rrggbb.

#Clicks

A row, block, button or empty state with a target tells the script when it's clicked: the panel or tab's on_click handler gets the target (and a chip's target gets target:chip). One with a command runs that command instead, notesy's own or a plugin's. See notesy::views.

#Inputs

Parts the user changes. Each needs a target to be heard: when it changes, the panel or tab's on_change handler gets the target, the new value, and the note's path (or None), and then notesy builds the view again, so what it shows comes from the script (notesy::views).

It's dropdown and not select because select is one of Rune's own words: a function by that name can be offered but never called.

selected is the one picked: by what it's worth, then by its name, then by its place from 0.

options is a list. An option is its name alone, or a table when it has more to say than that: value is what target hears when it's picked (its name, unless it's given one of its own), subline is a second line under its name, detail is faint text at its right, and icon is an icon before it, notesy's or the plugin's own. An option with a subline is given a taller row; the rest stay as they are. A segmented choice has room for neither subline nor detail and leaves both out.

rustuse notesy::{store, view, views};

pub fn ready() {
    views::panel("spans", "Spans", |note| {
        let spans = [
            #{ value: "day", label: "Day", subline: "Since midnight", detail: "24 hours", icon: "clock" },
            #{ value: "week", label: "Week", subline: "From Monday", detail: "7 days", icon: "calendar" },
        ];
        let span = view::dropdown(spans, store::get("span").unwrap_or("week"));
        span.target = "span";
        view::column([span])
    });
}

Written as plain text (["Day", "Week"]), an option is its own name and its own value, which is what every dropdown did before there was more to say.

rustuse notesy::{store, view, views};

pub fn ready() {
    let tasks = views::panel("tasks", "Tasks", |note| {
        let hide = view::switch("Hide done tasks", store::get("hide").unwrap_or(false));
        hide.target = "hide";
        let span = view::segmented(["Today", "This week"], store::get("span").unwrap_or("Today"));
        span.target = "span";
        view::column([hide, span])
    });
    tasks.on_change(|target, value, note| store::set(target, value));
}

#Suggestions

A field with suggest: true asks its script what to suggest as it's typed in. Once typing pauses (a quarter of a second), the panel or tab's on_suggest handler gets the target, the text and the note's path, and answers with the view's suggest(target, text, items): then, or later, once it knows. So what it suggests can come from anywhere it may reach: its store, the vault, a site its manifest names (notesy::net).

Each item is text, or #{ text, detail, icon, value, view }. They show under the field, to pick with ↑, ↓ and Enter or a click; Esc puts them away. One with a view (any part of a view: a column of a title and a line under it, a row with a pill) shows that instead of its icon, text and detail, lit and picked as the rest are; what's in it is only looked at. A pick reaches on_change with the item's value (its text, unless it has one); Enter with none lit sends what was typed, as a field without suggestions does. Only the answer for what was last typed shows, so one that comes back late is left out. At most 50 show.

rustuse notesy::{json, net, store, view, views};

pub fn ready() {
    let app = #{ panel: () };
    app.panel = views::panel("places", "Places", |note| {
        let add = view::input("Add a place");
        add.target = "add";
        add.suggest = true;
        view::column([add])
    });
    app.panel.on_suggest(|target, text, note| {
        net::fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${net::encode(text)}`, |result| {
            let items = [];
            if let Ok(response) = result {
                if let Ok(answer) = json::parse(response.text) {
                    for r in answer.get("results").unwrap_or([]) {
                        items.push(#{ text: r.name, detail: r.country, icon: "pin", value: `${r.name}, ${r.country}` });
                    }
                }
            }
            app.panel.suggest(target, text, items);
        });
    });
    // What was picked (its value), or typed and sent with Enter.
    app.panel.on_change(|target, value, note| store::set("place", value));
}

#Coming in

Any part can come in as it first shows: set its enter to how. notesy plays it as its Motion setting says (with motion off, parts are simply there): when the part first shows, as the panel opens or a new row turns up, and again after it's been out of sight a while. Building the view again doesn't play it again.

For more say, enter is an object, #{ kind: "rise", delay: 0.2, span: 0.4, ease: "back" }: delay seconds before it starts (up to 5), over span seconds (0.3 unless it says; up to 2), eased by name as a drawing's keyframes are (notesy::icons). A column with a stagger brings its parts in one after another, each that many seconds after the one before (up to 1): a list settling in. A stagger on its own rises.

rustuse notesy::{view, Icon};

fn build(note) {
    let rows = [];
    for task in ["Call Ana", "Book the train", "Pack for Eryri"] {
        rows.push(view::row(Icon::Check, task));
    }
    let head = view::header(Icon::Check, "Tasks", "3 left in this note");
    head.enter = "fade";
    let list = view::column(rows);
    list.enter = "rise";
    list.stagger = 0.04;
    view::column([head, list])
}

#When something's wrong

A part that's wrong (no text on a row, a kind there isn't) shows as a red line where it was, saying what's wrong, and the rest of the view still shows. A view has at most 2,000 parts, nested at most 16 deep.

Every page

• Overview
• plugin.toml: Every field of plugin.toml
• Permissions: What a plugin can ask for, when notesy asks, and what changes it
• Scripts: How a script runs: its lifecycle, events, limits and errors
• Packing and installing: Making, checking, signing, packing and installing
• notesy::log: Lines for its log on the Plugins page
• notesy::events: Hearing what happens, and every event
• notesy::commands: Adding commands, and running notesy's
• notesy::store: Keeping its own data
• notesy::settings: Reading its settings
• notesy::secrets: Keys and tokens, in the system keychain
• notesy::notes: Reading and changing the vault's notes
• notesy::editor: The note in front
• notesy::templates: What templates fill in, and functions of its own for them
• notesy::files: A folder of its own
• notesy::links: Opening pages in the browser, naming links after their pages
• notesy::clipboard: Copying and pasting
• notesy::view: What panels, tabs and sections show
• notesy::sections: Sidebar sections
• notesy::hidden: Hiding notes, files and folders from the tree
• notesy::status: Status bar items
• notesy::tools: Buttons in the formatting bar
• notesy::notices: Notices
• notesy::dialogs: Asking in a dialog, notesy's kinds or its own
• notesy::wizards: Pages one after another, like a setup
• notesy::boards: Boards' cards and arrows, and kinds of card of its own
• notesy::blocks: Drawing its fenced blocks
• notesy::icons: Drawing its own icons
• notesy::net: Requests to the sites it names
• notesy::ipc: Talking to a program on this computer
• notesy::accounts: Signing in to a service
• notesy::json: Reading and writing JSON
• notesy::toml: Reading and writing TOML
• notesy::yaml: Reading and writing YAML, and a note's front matter
• notesy::time: Now, written in the user's time zone, dates read, how long ago
• notesy::math: Trigonometry and the like, for drawing
• Names: Icon, Color, Tone, Side, Method, Command, Zone, Event: Notesy's names as enums
• notesy::preview: Its own screens for notesy preview
• notesy::perf: Timing its own work
• notesy::drawings: Drawings' shapes, and buttons in their tool strip
• notesy::sound: Playing sounds, and making them as it runs
• notesy::tex: Math macros for every note's formulas
• notesy::views: Side panels, tabs of its own, and its part of the tree's hover cards
• notesy::zones: Notesy's own places — its menus, its bars and its headings