1#![forbid(unsafe_code)]
2
3use std::collections::HashMap;
39
40#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
45pub struct HelpId(pub u64);
46
47impl core::fmt::Display for HelpId {
48 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
49 write!(f, "help:{}", self.0)
50 }
51}
52
53#[derive(Debug, Clone, PartialEq, Eq)]
55pub struct Keybinding {
56 pub key: String,
58 pub action: String,
60}
61
62impl Keybinding {
63 #[must_use]
65 pub fn new(key: impl Into<String>, action: impl Into<String>) -> Self {
66 Self {
67 key: key.into(),
68 action: action.into(),
69 }
70 }
71}
72
73impl<A> From<&ftui_core::keybinding::Binding<A>> for Keybinding {
74 fn from(binding: &ftui_core::keybinding::Binding<A>) -> Self {
75 Self {
76 key: binding.chord.to_string(),
77 action: binding.label.clone().unwrap_or_default(),
78 }
79 }
80}
81
82#[derive(Debug, Clone, PartialEq, Eq)]
84pub struct HelpContent {
85 pub short: String,
87 pub long: Option<String>,
89 pub keybindings: Vec<Keybinding>,
91 pub see_also: Vec<HelpId>,
93}
94
95impl HelpContent {
96 #[must_use]
98 pub fn short(desc: impl Into<String>) -> Self {
99 Self {
100 short: desc.into(),
101 long: None,
102 keybindings: Vec::new(),
103 see_also: Vec::new(),
104 }
105 }
106}
107
108type LazyProvider = Box<dyn FnOnce() -> HelpContent + Send>;
112
113enum Entry {
115 Loaded(HelpContent),
116 Lazy(LazyProvider),
117}
118
119impl core::fmt::Debug for Entry {
120 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
121 match self {
122 Self::Loaded(c) => f.debug_tuple("Loaded").field(c).finish(),
123 Self::Lazy(_) => f.debug_tuple("Lazy").field(&"<fn>").finish(),
124 }
125 }
126}
127
128#[derive(Debug)]
136pub struct HelpRegistry {
137 entries: HashMap<HelpId, Entry>,
138 parents: HashMap<HelpId, HelpId>,
141}
142
143impl Default for HelpRegistry {
144 fn default() -> Self {
145 Self::new()
146 }
147}
148
149impl HelpRegistry {
150 #[must_use]
152 pub fn new() -> Self {
153 Self {
154 entries: HashMap::new(),
155 parents: HashMap::new(),
156 }
157 }
158
159 pub fn register(&mut self, id: HelpId, content: HelpContent) {
163 self.entries.insert(id, Entry::Loaded(content));
164 }
165
166 pub fn register_lazy(
170 &mut self,
171 id: HelpId,
172 provider: impl FnOnce() -> HelpContent + Send + 'static,
173 ) {
174 self.entries.insert(id, Entry::Lazy(Box::new(provider)));
175 }
176
177 pub fn unregister(&mut self, id: HelpId) -> bool {
181 self.entries.remove(&id).is_some()
182 }
183
184 pub fn set_parent(&mut self, child: HelpId, parent: HelpId) -> bool {
192 if child == parent {
194 return false;
195 }
196 let mut cursor = parent;
197 while let Some(&ancestor) = self.parents.get(&cursor) {
198 if ancestor == child {
199 return false;
200 }
201 cursor = ancestor;
202 }
203 self.parents.insert(child, parent);
204 true
205 }
206
207 pub fn clear_parent(&mut self, child: HelpId) {
209 self.parents.remove(&child);
210 }
211
212 #[must_use = "use the returned help content (if any)"]
216 pub fn get(&mut self, id: HelpId) -> Option<&HelpContent> {
217 if matches!(self.entries.get(&id), Some(Entry::Lazy(_)))
219 && let Some(Entry::Lazy(provider)) = self.entries.remove(&id)
220 {
221 let content = provider();
222 self.entries.insert(id, Entry::Loaded(content));
223 }
224 match self.entries.get(&id) {
225 Some(Entry::Loaded(c)) => Some(c),
226 _ => None,
227 }
228 }
229
230 #[must_use = "use the returned help content (if any)"]
232 pub fn peek(&self, id: HelpId) -> Option<&HelpContent> {
233 match self.entries.get(&id) {
234 Some(Entry::Loaded(c)) => Some(c),
235 _ => None,
236 }
237 }
238
239 #[must_use = "use the returned help content (if any)"]
244 pub fn resolve(&mut self, id: HelpId) -> Option<&HelpContent> {
245 let chain = self.ancestor_chain(id);
247 for &cid in &chain {
249 if matches!(self.entries.get(&cid), Some(Entry::Lazy(_)))
250 && let Some(Entry::Lazy(provider)) = self.entries.remove(&cid)
251 {
252 let content = provider();
253 self.entries.insert(cid, Entry::Loaded(content));
254 }
255 }
256 for &cid in &chain {
258 if let Some(Entry::Loaded(c)) = self.entries.get(&cid) {
259 return Some(c);
260 }
261 }
262 None
263 }
264
265 #[must_use]
267 pub fn contains(&self, id: HelpId) -> bool {
268 self.entries.contains_key(&id)
269 }
270
271 #[inline]
273 #[must_use]
274 pub fn len(&self) -> usize {
275 self.entries.len()
276 }
277
278 #[inline]
280 #[must_use]
281 pub fn is_empty(&self) -> bool {
282 self.entries.is_empty()
283 }
284
285 pub fn ids(&self) -> impl Iterator<Item = HelpId> + '_ {
287 self.entries.keys().copied()
288 }
289
290 fn ancestor_chain(&self, id: HelpId) -> Vec<HelpId> {
292 let mut chain = vec![id];
293 let mut cursor = id;
294 while let Some(&parent) = self.parents.get(&cursor) {
295 chain.push(parent);
296 cursor = parent;
297 }
298 chain
299 }
300}
301
302#[cfg(test)]
303mod tests {
304 use super::*;
305
306 fn sample_content(short: &str) -> HelpContent {
307 HelpContent {
308 short: short.into(),
309 long: None,
310 keybindings: Vec::new(),
311 see_also: Vec::new(),
312 }
313 }
314
315 #[test]
318 fn register_and_get() {
319 let mut reg = HelpRegistry::new();
320 let id = HelpId(1);
321 reg.register(id, sample_content("tooltip"));
322 assert_eq!(reg.get(id).unwrap().short, "tooltip");
323 }
324
325 #[test]
326 fn missing_key_returns_none() {
327 let mut reg = HelpRegistry::new();
328 assert!(reg.get(HelpId(999)).is_none());
329 }
330
331 #[test]
332 fn register_overwrites() {
333 let mut reg = HelpRegistry::new();
334 let id = HelpId(1);
335 reg.register(id, sample_content("old"));
336 reg.register(id, sample_content("new"));
337 assert_eq!(reg.get(id).unwrap().short, "new");
338 }
339
340 #[test]
341 fn unregister() {
342 let mut reg = HelpRegistry::new();
343 let id = HelpId(1);
344 reg.register(id, sample_content("x"));
345 assert!(reg.unregister(id));
346 assert!(reg.get(id).is_none());
347 assert!(!reg.unregister(id));
348 }
349
350 #[test]
351 fn len_and_is_empty() {
352 let mut reg = HelpRegistry::new();
353 assert!(reg.is_empty());
354 assert_eq!(reg.len(), 0);
355 reg.register(HelpId(1), sample_content("a"));
356 reg.register(HelpId(2), sample_content("b"));
357 assert_eq!(reg.len(), 2);
358 assert!(!reg.is_empty());
359 }
360
361 #[test]
362 fn contains() {
363 let mut reg = HelpRegistry::new();
364 let id = HelpId(1);
365 assert!(!reg.contains(id));
366 reg.register(id, sample_content("x"));
367 assert!(reg.contains(id));
368 }
369
370 #[test]
371 fn ids_iteration() {
372 let mut reg = HelpRegistry::new();
373 reg.register(HelpId(10), sample_content("a"));
374 reg.register(HelpId(20), sample_content("b"));
375 let mut ids: Vec<_> = reg.ids().collect();
376 ids.sort_by_key(|h| h.0);
377 assert_eq!(ids, vec![HelpId(10), HelpId(20)]);
378 }
379
380 #[test]
383 fn lazy_provider_called_on_get() {
384 let mut reg = HelpRegistry::new();
385 let id = HelpId(1);
386 reg.register_lazy(id, || sample_content("lazy"));
387 assert!(reg.peek(id).is_none()); assert_eq!(reg.get(id).unwrap().short, "lazy");
389 assert!(reg.peek(id).is_some()); }
391
392 #[test]
393 fn lazy_provider_overwritten_by_register() {
394 let mut reg = HelpRegistry::new();
395 let id = HelpId(1);
396 reg.register_lazy(id, || sample_content("lazy"));
397 reg.register(id, sample_content("eager"));
398 assert_eq!(reg.get(id).unwrap().short, "eager");
399 }
400
401 #[test]
402 fn register_overwrites_lazy() {
403 let mut reg = HelpRegistry::new();
404 let id = HelpId(1);
405 reg.register_lazy(id, || sample_content("first"));
406 reg.register_lazy(id, || sample_content("second"));
407 assert_eq!(reg.get(id).unwrap().short, "second");
408 }
409
410 #[test]
413 fn resolve_walks_parents() {
414 let mut reg = HelpRegistry::new();
415 let child = HelpId(1);
416 let parent = HelpId(2);
417 let grandparent = HelpId(3);
418
419 reg.register(grandparent, sample_content("app help"));
420 reg.set_parent(child, parent);
421 reg.set_parent(parent, grandparent);
422
423 assert_eq!(reg.resolve(child).unwrap().short, "app help");
425 }
426
427 #[test]
428 fn resolve_prefers_nearest() {
429 let mut reg = HelpRegistry::new();
430 let child = HelpId(1);
431 let parent = HelpId(2);
432 let grandparent = HelpId(3);
433
434 reg.register(parent, sample_content("container help"));
435 reg.register(grandparent, sample_content("app help"));
436 reg.set_parent(child, parent);
437 reg.set_parent(parent, grandparent);
438
439 assert_eq!(reg.resolve(child).unwrap().short, "container help");
441 }
442
443 #[test]
444 fn resolve_returns_own_content_first() {
445 let mut reg = HelpRegistry::new();
446 let child = HelpId(1);
447 let parent = HelpId(2);
448
449 reg.register(child, sample_content("widget help"));
450 reg.register(parent, sample_content("container help"));
451 reg.set_parent(child, parent);
452
453 assert_eq!(reg.resolve(child).unwrap().short, "widget help");
454 }
455
456 #[test]
457 fn resolve_no_content_returns_none() {
458 let mut reg = HelpRegistry::new();
459 let child = HelpId(1);
460 let parent = HelpId(2);
461 reg.set_parent(child, parent);
462 assert!(reg.resolve(child).is_none());
463 }
464
465 #[test]
466 fn set_parent_rejects_self_cycle() {
467 let mut reg = HelpRegistry::new();
468 let id = HelpId(1);
469 assert!(!reg.set_parent(id, id));
470 }
471
472 #[test]
473 fn set_parent_rejects_indirect_cycle() {
474 let mut reg = HelpRegistry::new();
475 let a = HelpId(1);
476 let b = HelpId(2);
477 let c = HelpId(3);
478
479 assert!(reg.set_parent(a, b));
480 assert!(reg.set_parent(b, c));
481 assert!(!reg.set_parent(c, a));
483 }
484
485 #[test]
486 fn clear_parent() {
487 let mut reg = HelpRegistry::new();
488 let child = HelpId(1);
489 let parent = HelpId(2);
490
491 reg.register(parent, sample_content("parent"));
492 reg.set_parent(child, parent);
493 assert!(reg.resolve(child).is_some());
494
495 reg.clear_parent(child);
496 assert!(reg.resolve(child).is_none());
497 }
498
499 #[test]
502 fn keybindings_stored() {
503 let mut reg = HelpRegistry::new();
504 let id = HelpId(1);
505 reg.register(
506 id,
507 HelpContent {
508 short: "Editor".into(),
509 long: Some("Main text editor".into()),
510 keybindings: vec![
511 Keybinding::new("Ctrl+S", "Save"),
512 Keybinding::new("Ctrl+Q", "Quit"),
513 ],
514 see_also: vec![HelpId(2)],
515 },
516 );
517 let content = reg.get(id).unwrap();
518 assert_eq!(content.keybindings.len(), 2);
519 assert_eq!(content.keybindings[0].key, "Ctrl+S");
520 assert_eq!(content.keybindings[0].action, "Save");
521 assert_eq!(content.see_also, vec![HelpId(2)]);
522 }
523
524 #[test]
525 fn help_content_short_constructor() {
526 let c = HelpContent::short("tooltip");
527 assert_eq!(c.short, "tooltip");
528 assert!(c.long.is_none());
529 assert!(c.keybindings.is_empty());
530 assert!(c.see_also.is_empty());
531 }
532
533 #[test]
534 fn help_id_display() {
535 assert_eq!(HelpId(42).to_string(), "help:42");
536 }
537
538 #[test]
541 fn resolve_forces_lazy_in_parent() {
542 let mut reg = HelpRegistry::new();
543 let child = HelpId(1);
544 let parent = HelpId(2);
545
546 reg.register_lazy(parent, || sample_content("lazy parent"));
547 reg.set_parent(child, parent);
548
549 assert_eq!(reg.resolve(child).unwrap().short, "lazy parent");
550 assert!(reg.peek(parent).is_some());
552 }
553
554 #[test]
557 fn empty_registry_resolve() {
558 let mut reg = HelpRegistry::new();
559 assert!(reg.resolve(HelpId(1)).is_none());
560 }
561
562 #[test]
563 fn deep_hierarchy() {
564 let mut reg = HelpRegistry::new();
565 for i in 0..4u64 {
567 assert!(reg.set_parent(HelpId(i), HelpId(i + 1)));
568 }
569 reg.register(HelpId(4), sample_content("root"));
570 assert_eq!(reg.resolve(HelpId(0)).unwrap().short, "root");
571 }
572
573 #[test]
574 fn set_parent_allows_reparenting() {
575 let mut reg = HelpRegistry::new();
576 let child = HelpId(1);
577 let p1 = HelpId(2);
578 let p2 = HelpId(3);
579
580 reg.register(p1, sample_content("first parent"));
581 reg.register(p2, sample_content("second parent"));
582
583 reg.set_parent(child, p1);
584 assert_eq!(reg.resolve(child).unwrap().short, "first parent");
585
586 reg.set_parent(child, p2);
588 assert_eq!(reg.resolve(child).unwrap().short, "second parent");
589 }
590
591 #[test]
592 fn unregister_does_not_remove_parent_link() {
593 let mut reg = HelpRegistry::new();
594 let child = HelpId(1);
595 let parent = HelpId(2);
596 let grandparent = HelpId(3);
597
598 reg.register(parent, sample_content("parent"));
599 reg.register(grandparent, sample_content("grandparent"));
600 reg.set_parent(child, parent);
601 reg.set_parent(parent, grandparent);
602
603 reg.unregister(parent);
605 assert_eq!(reg.resolve(child).unwrap().short, "grandparent");
606 }
607}