aylis_core/question.rs
1//! Eventos que perguntam (item 3 dos ajustes): o `on_close_query` (`CanClose`), o
2//! `before_post` e o `before_delete` (recusar a gravação), o `on_validate` do campo, o
3//! `on_key_down`/`on_key_press` (engolir ou trocar a tecla), o `on_drag_start` e o
4//! `on_drag_over`. Quem dispara pergunta com [`Ui::ask`] e recebe a resposta:
5//!
6//! - um handler em Rust responde na hora, dentro do `fire`: [`Ui::refuse`] recusa (o `Err`
7//! do handler que devolve `Result`), [`Ui::reply`] grava um campo da resposta
8//! (`can_close`, `key`, `data`...);
9//! - um handler que não pode responder já (o backend em outra linguagem, um handler do mesmo
10//! form que espera o que roda terminar) adia com [`Ui::defer_question`] e responde depois
11//! com [`Ui::answer`]; quem perguntou recebe [`Asked::Deferred`] e diz, com
12//! [`Ui::on_answer`], o que fazer quando a resposta chegar (fechar o form, gravar o
13//! registro, entregar a tecla).
14//!
15//! Sem handler, a resposta é aceitar.
16
17use std::collections::HashMap;
18use std::rc::Rc;
19
20use crate::component::ComponentId;
21use crate::event::EventArgs;
22use crate::prop::PropValue;
23use crate::ui::Ui;
24
25/// A resposta a um evento-pergunta.
26#[derive(Clone, Debug, PartialEq)]
27pub enum Answer {
28 /// Aceito, com os campos que o handler respondeu (`can_close`, `key`...).
29 Accepted(Vec<(String, PropValue)>),
30 /// Recusado (a exceção do handler; a mensagem vai para a tela, vazia para recusar calado).
31 Refused(String),
32}
33
34impl Answer {
35 /// O campo respondido (`None` se o handler não mexeu nele).
36 pub fn value(&self, name: &str) -> Option<&PropValue> {
37 match self {
38 Answer::Accepted(values) => values.iter().rev().find(|(n, _)| n == name).map(|(_, v)| v),
39 Answer::Refused(_) => None,
40 }
41 }
42
43 /// O campo booleano respondido, ou `default`.
44 pub fn flag(&self, name: &str, default: bool) -> bool {
45 match self.value(name) {
46 Some(PropValue::Bool(b)) => *b,
47 _ => default,
48 }
49 }
50
51 pub fn is_refused(&self) -> bool {
52 matches!(self, Answer::Refused(_))
53 }
54}
55
56/// O que [`Ui::ask`] devolve.
57#[derive(Clone, Debug, PartialEq)]
58pub enum Asked {
59 /// O handler respondeu na hora (ou não havia handler: aceito, sem campos).
60 Answered(Answer),
61 /// O handler vai responder depois: o número da pergunta, para o [`Ui::on_answer`].
62 Deferred(u64),
63}
64
65/// O que fazer quando a resposta de uma pergunta adiada chegar.
66type Continuation = Box<dyn FnOnce(&mut Ui, Answer)>;
67
68/// Uma pergunta em andamento (a pilha: um handler pode perguntar de novo).
69#[derive(Default)]
70struct Frame {
71 /// O evento que perguntou (o interceptador sabe se a pergunta é a do evento dele).
72 target: Option<(ComponentId, String)>,
73 refused: Option<String>,
74 values: Vec<(String, PropValue)>,
75 deferred: Option<u64>,
76 /// O handler da pergunta já foi despachado (o primeiro `with_form` dela): um `with_form`
77 /// de dentro do handler, adiado por achar o form ocupado, não leva a pergunta junto.
78 claimed: bool,
79}
80
81#[derive(Default)]
82pub(crate) struct Questions {
83 stack: Vec<Frame>,
84 next: u64,
85 /// As adiadas: quem perguntou (o caminho, para o log) e o que fazer na resposta.
86 waiting: HashMap<u64, (ComponentId, String, Option<Continuation>)>,
87 /// As respostas que chegaram antes do `on_answer` (o handler respondeu dentro do próprio
88 /// `fire`, depois de adiar).
89 early: HashMap<u64, Answer>,
90 /// Os forms cujo `on_close_query` espera o backend, e os que a resposta já liberou.
91 pub(crate) closes: Vec<ComponentId>,
92 pub(crate) closing_now: Vec<ComponentId>,
93 pub(crate) unresponsive: Option<Rc<dyn Fn(&mut Ui, ComponentId)>>,
94 pub(crate) terminate: Option<Rc<dyn Fn(&mut Ui)>>,
95}
96
97impl Ui {
98 /// Dispara o evento-pergunta `event` de `id` e devolve a resposta (veja o módulo).
99 pub fn ask(&mut self, id: ComponentId, event: &str, args: &EventArgs) -> Asked {
100 self.questions.stack.push(Frame { target: Some((id, event.to_string())), ..Frame::default() });
101 self.fire(id, event, args);
102 let frame = self.questions.stack.pop().unwrap_or_default();
103 if let Some(token) = frame.deferred {
104 self.questions.waiting.entry(token).or_insert((id, event.to_string(), None));
105 return Asked::Deferred(token);
106 }
107 Asked::Answered(match frame.refused {
108 Some(message) => Answer::Refused(message),
109 None => Answer::Accepted(frame.values),
110 })
111 }
112
113 /// A pergunta em andamento é a do evento `event` de `id` (e ainda não foi adiada).
114 pub(crate) fn question_is_for(&self, id: ComponentId, event: &str) -> bool {
115 self.questions.stack.last().is_some_and(|f| f.deferred.is_none() && f.target.as_ref().is_some_and(|(i, e)| *i == id && e == event))
116 }
117
118 /// O despacho do handler da pergunta em andamento: `true` só na primeira vez (o
119 /// `with_form` que roda o handler dela); as chamadas de dentro do handler recebem `false`.
120 /// Sem isso, o `with_form` que o handler do `on_back` fazia no próprio form (ocupado) era
121 /// adiado levando a pergunta, e a resposta `handled` do handler se perdia (relatado pelo
122 /// RTSPlayer em 14/11: voltar do player trocava a tela e mandava o app para segundo plano).
123 pub(crate) fn claim_question(&mut self) -> bool {
124 match self.questions.stack.last_mut() {
125 Some(f) if f.deferred.is_none() && !f.claimed => {
126 f.claimed = true;
127 true
128 }
129 _ => false,
130 }
131 }
132
133 /// `true` dentro do handler de um evento-pergunta (o receptor remoto manda o evento com o
134 /// número da pergunta e adia).
135 pub fn asking(&self) -> bool {
136 self.questions.stack.last().is_some_and(|f| f.deferred.is_none())
137 }
138
139 /// Dentro de um evento-pergunta: recusa. A
140 /// mensagem vai para a tela; vazia, recusa calado.
141 pub fn refuse(&mut self, message: impl Into<String>) {
142 if let Some(frame) = self.questions.stack.last_mut() {
143 frame.refused = Some(message.into());
144 }
145 }
146
147 /// Dentro de um evento-pergunta: grava um campo da resposta (`can_close`, `key`,
148 /// `key_char`, `data`, `label`, `accept`).
149 pub fn reply(&mut self, name: &str, value: impl Into<PropValue>) {
150 if let Some(frame) = self.questions.stack.last_mut() {
151 frame.values.push((name.to_string(), value.into()));
152 }
153 }
154
155 /// Dentro de um evento-pergunta: a resposta vem depois, por [`answer`](Self::answer) com o
156 /// número devolvido. Fora de uma pergunta, devolve 0 (e o `answer(0, ..)` não faz nada).
157 pub fn defer_question(&mut self) -> u64 {
158 let Some(frame) = self.questions.stack.last_mut() else { return 0 };
159 if let Some(token) = frame.deferred {
160 return token;
161 }
162 self.questions.next += 1;
163 let token = self.questions.next;
164 frame.deferred = Some(token);
165 token
166 }
167
168 /// O que fazer quando a resposta da pergunta adiada `token` chegar (se já chegou, roda
169 /// agora).
170 pub fn on_answer(&mut self, token: u64, f: impl FnOnce(&mut Ui, Answer) + 'static) {
171 if let Some(answer) = self.questions.early.remove(&token) {
172 self.questions.waiting.remove(&token);
173 f(self, answer);
174 return;
175 }
176 if let Some(entry) = self.questions.waiting.get_mut(&token) {
177 entry.2 = Some(Box::new(f));
178 }
179 }
180
181 /// A resposta da pergunta adiada `token` (o backend respondeu). Devolve `false` se não
182 /// havia essa pergunta (já respondida, ou o número é de outra tela).
183 pub fn answer(&mut self, token: u64, answer: Answer) -> bool {
184 let Some((_, _, continuation)) = self.questions.waiting.remove(&token) else {
185 // Adiada e respondida dentro do mesmo `fire` (antes de o `ask` voltar).
186 if token != 0 && token <= self.questions.next && self.questions.stack.iter().any(|f| f.deferred == Some(token)) {
187 self.questions.early.insert(token, answer);
188 return true;
189 }
190 return false;
191 };
192 match continuation {
193 Some(f) => f(self, answer),
194 None => {
195 self.questions.early.insert(token, answer);
196 }
197 }
198 true
199 }
200
201 /// Responde à pergunta adiada `token` rodando `f` como se fosse o handler: o que ele
202 /// recusar ou responder vira a resposta. É como um handler do mesmo form, que esperou o
203 /// outro terminar, responde.
204 pub fn answering(&mut self, token: u64, f: impl FnOnce(&mut Ui)) {
205 self.questions.stack.push(Frame::default());
206 f(self);
207 let frame = self.questions.stack.pop().unwrap_or_default();
208 let answer = match frame.refused {
209 Some(message) => Answer::Refused(message),
210 None => Answer::Accepted(frame.values),
211 };
212 // Adiou de novo (um backend dentro do handler adiado): a resposta é a dele.
213 if let Some(inner) = frame.deferred {
214 self.on_answer(inner, move |ui, a| {
215 ui.answer(token, a);
216 });
217 return;
218 }
219 self.answer(token, answer);
220 }
221
222 /// A tecla Voltar do celular (decidido em 14/11; o RTSPlayer troca de tela por frames e a
223 /// tecla tirava o app da frente): pergunta ao `on_back` do form do topo. Respondido
224 /// `handled` (ou recusado), o app tratou e nada mais acontece; senão, `default` faz o de
225 /// sempre (a plataforma: cancelar o modal, fechar o form aberto, o principal para segundo
226 /// plano). Com o backend em outra linguagem, a resposta chega depois e o `default` espera.
227 pub fn back_pressed(&mut self, default: impl FnOnce(&mut Ui) + 'static) {
228 let Some(form) = self.open_forms().last().copied() else {
229 default(self);
230 return;
231 };
232 let handled = |answer: &Answer| answer.is_refused() || answer.flag("handled", false);
233 match self.ask(form, "on_back", &EventArgs::None) {
234 Asked::Answered(answer) => {
235 if !handled(&answer) {
236 default(self);
237 }
238 }
239 Asked::Deferred(token) => self.on_answer(token, move |ui, answer| {
240 if !handled(&answer) {
241 default(ui);
242 }
243 }),
244 }
245 }
246
247 /// As perguntas que esperam resposta (para a tela saber que o backend está devendo).
248 pub fn questions_waiting(&self) -> usize {
249 self.questions.waiting.len()
250 }
251
252 /// Esquece as perguntas de componentes liberados.
253 pub(crate) fn forget_questions(&mut self, doomed: &[ComponentId]) {
254 if !self.questions.waiting.is_empty() {
255 self.questions.waiting.retain(|_, (id, _, _)| !doomed.contains(id));
256 }
257 }
258}
259
260/// Os eventos que perguntam e os campos da resposta de cada um (o catálogo marca, e a IDE
261/// gera o esqueleto com a assinatura certa). Sem campos: só aceitar ou recusar.
262pub const QUESTION_EVENTS: &[(&str, &[&str])] = &[
263 ("on_close_query", &["can_close"]),
264 // A tecla Voltar do celular: `handled` diz que o app tratou (voltou a tela de dentro).
265 ("on_back", &["handled"]),
266 ("before_post", &[]),
267 ("before_delete", &[]),
268 ("on_validate", &[]),
269 ("on_key_down", &["key"]),
270 ("on_key_press", &["key"]),
271 ("on_drag_start", &["data", "label"]),
272 ("on_drag_over", &["accept"]),
273 ("on_apply_updates", &["results"]),
274 ("on_intercept", &["cancel"]),
275 ("before_action", &[]),
276 // O MCP (`aylis_remote::mcp`): a ferramenta responde `result`; o servidor aceita ou recusa
277 // a chamada do agente.
278 ("on_execute", &["result"]),
279 ("on_call", &[]),
280];
281
282/// Os campos da resposta do evento-pergunta `event` (`None` se não é pergunta).
283pub fn question_fields(event: &str) -> Option<&'static [&'static str]> {
284 QUESTION_EVENTS.iter().find(|(e, _)| *e == event).map(|(_, f)| *f)
285}
286
287/// Os eventos que se juntam enquanto o anterior (do mesmo componente) não terminou no backend
288/// (o catálogo marca; veja `aylis_remote::coalesces`). Clique e tecla nunca se juntam.
289pub const COALESCED_EVENTS: &[&str] = &["on_timer", "on_resize", "on_scroll", "on_pointer_move", "on_wheel", "on_progress", "on_frame"];