Reusable commands

day::Command is a named-field definition of an application’s operation. Calling .build() returns a cloneable day::CommandHandle that shares its behavior and presentation metadata. Both types are in the prelude and live in day-pieces, above the toolkit-neutral menu, toolbar, and button models. There is no new backend protocol, global action registry, or toolkit dependency. Each presentation keeps its normal native widget and dispatch registration; the command shares Rust behavior and state.

Define once, present in several places

use day::prelude::*;

fn counter() -> impl Piece {
    let count = Signal::new(0);
    let add = Command {
        id: "add",
        label: "Add one",
        action: move || count.update(|n| *n += 1),
    }
    .build()
    .enabled(move || count.get() < 3)
    .icon(Symbol::Add)
    .shortcut(Shortcut::new("+"));
    let menu = add.clone();
    let toolbar = add.clone();
    column((
        label(move || count.get().to_string()),
        add.button(),
        label("More actions").context_menu_fn(move |_| vec![menu.menu_item()]),
    ))
    .toolbar(move || vec![toolbar.toolbar_item()])
}

In an app, pass res::str::add() instead of a literal. The title accepts the same IntoText inputs as a button: localized text, strings, signals, and Fn() -> String. Availability and optional check state accept booleans, signals, or closures. Reactive reads are tracked when the presentation evaluates them. A changing label can therefore say “Star” or “Unstar” from the same state that supplies .checked(move || starred.get()).

Optional modifiers and presentation methods belong to CommandHandle, after .build(). The definition’s fields are generic: ids accept Into<String>, labels accept IntoText, and actions accept capturing Fn() closures without manual Rc wrapping or a Clone requirement. Command factories return CommandHandle, so callers need not name closure types:

fn refresh_command() -> CommandHandle {
    Command {
        id: "refresh",
        label: res::str::refresh(),
        action: refresh_document,
    }
    .build()
    .icon(Symbol::Refresh)
}

The handle’s builders configure values. Handle clones share their handler and reactive sources, but calling a builder on a clone does not mutate previously created commands or controls. Change a signal read by the definition to update existing presentations.

Reactive presentation and ids

Content buttons bind automatically. Use a derived toolbar for changing labels or locale:

let bar_command = save.clone();
content.toolbar(move || vec![bar_command.toolbar_item().id("save-toolbar")]);

Toolbar availability and check state also bind in a fixed list, but its title is a snapshot. A derived toolbar uses the existing contribution replacement/rebinding machinery. It is not a new per-frame binding or a timer. Dynamic menus should be built with app_menu_reactive, a reactive navigation-row mapper, or the per-summon context_menu_fn:

// Construct application-menu commands in application scope, not a disposable page.
let menu_save = save.clone();
app_menu_reactive(move || vec![sub_menu("File", vec![menu_save.menu_item()])]);

A fixed app_menu or context_menu(vec![...]) keeps its installed snapshot until replaced. Even a stale enabled snapshot cannot execute an unavailable command: the registered callback always calls invoke(). Do not override the adapter’s .action(...) if you want that guarantee. Presentation-specific .enabled(...) overrides likewise do not replace the command’s guard.

The command id is a default UI id, not a globally unique dispatch token. Buttons, menus, and toolbars retain their existing separate dispatch rules. Give two buttons in the same tree separate ids (command.button().id("save-footer")); keep toolbar ids unique within their chrome and menu ids unambiguous in the installed menu. Toolkit ids remain internal. Sharing a command does not register a second application-wide keyboard handler or resolve accelerator conflicts. Install a shortcut in one appropriate menu; do not assign the same accelerator to unrelated operations. Showcase’s screenshot command uses primary+Alt+S, clear of File > Save.

Ownership, windows, and checked commands

A command records Scope::current() at .build(), not at the struct literal. Build it in the scope that owns the operation. Constructing a definition elsewhere does not extend the lifetime of signals captured by its fields; those must still outlive its use. After disposal it is unavailable, invoke() is a no-op, its title reads empty, and an optional check reads false. This prevents an escaped command from touching its captured disposed signals. A retained clone still retains its captured Rust resources until dropped; it does not keep the reactive scope alive. Native registrations and bindings remain owned by their normal menu, toolbar contribution, or piece scopes.

Capture a particular window’s scene or row key for window/row commands. For an application-menu operation that should target the front window, explicitly resolve Scene::focused() (or the app’s equivalent) inside the state predicates and handler. Commands do not implicitly change focus, select a document, or retarget captured state. Two commands may have the same semantic id and act on independent window scenes. Build reusable command handles in their owning scope, not a short-lived rendering pass that should not own the operation.

A check is a read-only projection of app state. The command’s handler owns changes. A toolbar toggle request invokes the operation once when its requested state differs from the current check, then reads the resulting check back into the native widget, including when the handler declines to change state. Setting the already-current state is a no-op. This avoids an extra mirrored Signal<bool> and corrects toolkits that optimistically flip a toggle. The boolean payload expresses intent; the command never assigns its state directly. Use toolbar_toggle for a two-way boolean setter. A push button does not display checked state; use a changing title/icon, a separate toggle, or the menu/toolbar presentation.

Limits and platform behavior

This is an app-operation abstraction, not an implementation of native responder-chain editing. Keep menu_role(MenuRole::Copy/Undo/...) for focused text editing and OS commands. It is also not a command palette, undo stack, global hotkey manager, async executor, or automatic busy/error state machine. Start async work with the existing task APIs and include your own busy signal in .enabled(...). Direct custom gestures can call .invoke(); they must separately present the command’s title/availability/accessibility state. No automatic visibility or gesture styling is implied. Arguments can be captured by typed Rust command factories, without an erased payload API.

The detailed, evolving matrices live in menus, toolbars, and buttons. This API uses their existing spec models and event routing, on all targets. Windows behavior requires Windows runtime validation; an OpenHarmony compile-check does not claim emulator validation. dayscript toolbar: drives the model and is not proof that native chrome rendered; inspect screenshots too.

Sample-app audit and migrations

All eight Day-* sample applications and Games-Fair were reviewed. This is an operation-level refactor, not a mechanical replacement of every one-off .action(...).

The new mock regressions in crates/day-pieces/tests/mock_e2e.rs cover shared reactive labels, checked state, all invocation paths, stale enabled snapshots, scope disposal, independent captured state, and native toggle rejection. Showcase’s dayscript/commands.yaml covers button/toolbar interoperation, revisiting the page, shared menu/toolbar check state, and repeated desired-state requests. Existing app walkthroughs cover migrated operations.

Assessment: named definitions for other components

This section is an API assessment, not an announcement of additional component types. The named Command definition and CommandHandle are implemented; the component wrappers below are potential follow-up work.

Named fields help most when a call has several required arguments, especially multiple strings or callbacks. Rust spells this ActionButton { id: ..., text: ..., ... }, with braces; it does not support named arguments in ActionButton(...) calls. Such a definition can offer an explicit .into_piece() conversion, then retain the existing piece’s modifiers and decorators. For menu/toolbar entries, the corresponding conversion could be .into_entry().

Both forms can coexist. PascalCase types and snake_case functions have different names. Keep one implementation path: a definition converts through the existing constructor, or the function constructs a definition and delegates to its conversion. Neither should copy the other form’s reactive bindings, event handlers, or native lowering. Conversion itself need not add a heap allocation or a view node; retain the existing concrete return type where practical.

Most core pieces already have public type names (Button, Label, Picker, and so on), with private normalized fields and defaults. Making those internals public would require callers to construct TextSource, callback containers, and every default; it also exposes implementation details to future compatibility constraints. New definitions should use distinct names or an explicit namespace. Renaming all existing piece types to make room would be a much larger API migration than the new, unreleased command API.

An explicit conversion method is the simplest initial design. It allows text-conversion marker types to be inferred on that method, as with Command::build, and avoids duplicating the many typed builder traits on definitions. Implementing Piece directly on arbitrary generic definitions requires resolving those conversions and preserving modifier chaining; an inherent no-argument build() can also obscure Piece::build(self, &mut BuildCx). Use .into_piece() for such wrappers.

Recommendation: retain the established function forms, add named definitions selectively for long or ambiguous signatures, and document the equivalent forms together. Start with the local ActionButton helper and toolbar definitions. There is no need for a separate struct wrapper for every one-argument constructor or for every optional modifier.