Module choreography 

Choreographic Programming for multi-widget interactions (bd-14k2m).

Defines coordinated multi-widget behavior from a global specification and automatically projects it to per-widget message handlers.

Motivation

In Elm/Bubbletea architecture, coordinated behavior across multiple widgets requires manually routing messages. Missing a message means inconsistent state. Choreographic programming (Montesi 2013) eliminates this class of bugs by:

1. Define the choreography once (global specification).
2. Project to individual widgets automatically.
3. Guarantee completeness (no missing messages).

Example

use ftui_widgets::choreography::*;

let mut choreo = Choreography::new("filter_update");

// Global specification: when filter changes, update list + status + header
choreo.step("filter", Action::Emit("filter_changed".to_string()));
choreo.step(
    "list",
    Action::Handle("filter_changed".to_string(), "scroll_to_top".to_string()),
);
choreo.step(
    "status",
    Action::Handle("filter_changed".to_string(), "update_count".to_string()),
);
choreo.step(
    "header",
    Action::Handle("filter_changed".to_string(), "highlight_filter".to_string()),
);

// Project to per-widget handlers
let projection = choreo.project();
assert_eq!(projection.handlers("filter").len(), 1);
assert_eq!(projection.handlers("list").len(), 1);
assert_eq!(projection.handlers("status").len(), 1);
assert_eq!(projection.handlers("header").len(), 1);

// Verify deadlock freedom
assert!(choreo.verify_deadlock_free());

Structs

Choreography

A global choreography specification.

ChoreographyStep

A single step in a choreography.

CompletenessReport

Report on choreography completeness.

ExecutionEvent

An event from choreography execution.

ProjectedHandler

A projected handler for a single participant.

Projection

Projected per-participant handlers from a choreography.

Enums

Action

An action in a choreography step.

EventKind

Kind of execution event.

HandlerKind

Kind of projected handler.

Functions

example_filter_update

Filter update: filter dropdown → list + status bar + header.

example_modal_dialog

Modal dialog: trigger → overlay + dimmer + focus trap.

example_search_flow

Search flow: search input → results list → status + preview.

example_selection_sync

Selection sync: list selection → detail panel + status bar.

example_tab_navigation

Tab navigation: tab bar → content panel + breadcrumb + status.

execute_choreography

Execute a choreography against a set of participant state callbacks.

Type Aliases

MessageType

A message type exchanged between participants.

ParticipantId

A participant in a choreography (typically a widget).