Reusable commands

day::Command is an application operation: one id, one title, one availability, one handler. Command::new(id, label, action) builds it, and clones share its behavior and presentation metadata. The type is in the prelude and lives 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.

The UI snippets use generated res::str accessors from an app’s Fluent catalog; see the example messages and catalog setup.

Define once, present in several places

use day::prelude::*;

fn counter() -> impl Piece {
    let count = Signal::new(0);
    let add = Command::new(id!(add), res::str::add_one(), move || {
        count.update(|n| *n += 1)
    })
    .enabled(move || count.get() < 3)
    .icon(Symbol::Add)
    .shortcut(Shortcut::primary("+"));
    let menu = add.clone();
    let toolbar = add.clone();
    column((
        label(res::str::counter_value(count)).id(id!(counter_label)),
        add.button(),
        label(res::str::more_actions()).context_menu(move || vec![menu.menu_item()]),
    ))
    .toolbar(move || vec![toolbar.toolbar_item()])
}

The generated 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 chain onto the Command. The constructor’s parameters 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 Command, so callers need not name closure types:

fn refresh_command() -> Command {
    Command::new(id!(refresh), res::str::refresh(), refresh_document).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(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. The app menu is live (a Command::menu_item re-lowers the menu when its title or availability changes); a context menu is built per summon from a closure:

// Construct application-menu commands in application scope, not a disposable page.
let menu_save = save.clone();
app_menu(move || vec![sub_menu(res::str::file(), vec![menu_save.menu_item()])]);

A 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(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() in Command::new. Build it in the scope that owns the operation. Constructing it does not extend the lifetime of the signals its handler captures; 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 recorded an assessment (2026-09) of named-field definitions for other constructors, with the then-current Command { id, label, action }.build() as the model. The outcome is the house style in docs/api-style.md: a constructor keeps up to three positional, type-distinct arguments (Command::new(id, label, action) is one), coupled configuration is one value with its own builder (Search, ContentList, Reorder, Delete, Move), items are values (item(..), toolbar_button(..), menu_item(..), (value, title) picker options), and named fields are reserved for same-typed arguments, where the generated res::str argument structs use them (docs/localization.md). No .into_piece()/.into_entry() wrappers were added.