Skip to main content

ftui_widgets/
help_registry.rs

1#![forbid(unsafe_code)]
2
3//! Central registry for contextual help content.
4//!
5//! Maps widget IDs to structured help entries with hierarchical resolution
6//! (widget → container → app). Widgets register their help content via
7//! [`HelpRegistry::register`], and consumers look up help for a given widget
8//! via [`HelpRegistry::get`] or [`HelpRegistry::resolve`] (which walks the
9//! hierarchy).
10//!
11//! # Invariants
12//!
13//! 1. Each `HelpId` maps to at most one [`HelpContent`] at any given time.
14//! 2. [`resolve`](HelpRegistry::resolve) walks parents until it finds content
15//!    or reaches the root; it never cycles (parent chains are acyclic by
16//!    construction—[`set_parent`](HelpRegistry::set_parent) rejects cycles).
17//! 3. Lazy providers are called at most once per lookup; results are cached
18//!    in the registry for subsequent lookups.
19//!
20//! # Example
21//!
22//! ```
23//! use ftui_widgets::help_registry::{HelpRegistry, HelpContent, HelpId, Keybinding};
24//!
25//! let mut reg = HelpRegistry::new();
26//! let widget_id = HelpId(42);
27//!
28//! reg.register(widget_id, HelpContent {
29//!     short: "Save the current file".into(),
30//!     long: Some("Writes the buffer to disk, creating the file if needed.".into()),
31//!     keybindings: vec![Keybinding::new("Ctrl+S", "Save")],
32//!     see_also: vec![],
33//! });
34//!
35//! assert_eq!(reg.get(widget_id).unwrap().short, "Save the current file");
36//! ```
37
38use std::collections::HashMap;
39
40/// Unique identifier for a help-registered widget.
41///
42/// Typically corresponds to a [`FocusId`](crate::focus::FocusId) but is its
43/// own type so the help system can be used independently of focus management.
44#[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/// A keyboard shortcut associated with a widget.
54#[derive(Debug, Clone, PartialEq, Eq)]
55pub struct Keybinding {
56    /// Human-readable key combo (e.g. "Ctrl+S", "↑/k").
57    pub key: String,
58    /// What the binding does.
59    pub action: String,
60}
61
62impl Keybinding {
63    /// Create a new keybinding.
64    #[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/// Structured help content for a widget.
83#[derive(Debug, Clone, PartialEq, Eq)]
84pub struct HelpContent {
85    /// Short tooltip-length description (one line).
86    pub short: String,
87    /// Optional longer description shown in a detail panel.
88    pub long: Option<String>,
89    /// Keybindings available when this widget is focused.
90    pub keybindings: Vec<Keybinding>,
91    /// Related widget help IDs for "see also" links.
92    pub see_also: Vec<HelpId>,
93}
94
95impl HelpContent {
96    /// Create minimal help content with just a short description.
97    #[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
108/// A lazy provider that produces [`HelpContent`] on demand.
109///
110/// Providers are called at most once; the result is cached.
111type LazyProvider = Box<dyn FnOnce() -> HelpContent + Send>;
112
113/// Internal entry: either already-loaded content or a lazy provider.
114enum 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/// Central registry mapping widget IDs to help content.
129///
130/// Supports:
131/// - Direct registration via [`register`](Self::register)
132/// - Lazy/deferred registration via [`register_lazy`](Self::register_lazy)
133/// - Hierarchical parent chains via [`set_parent`](Self::set_parent)
134/// - Resolution that walks parent chain via [`resolve`](Self::resolve)
135#[derive(Debug)]
136pub struct HelpRegistry {
137    entries: HashMap<HelpId, Entry>,
138    /// Parent mapping: child → parent. Used by `resolve` to walk up the
139    /// widget tree when a widget has no help of its own.
140    parents: HashMap<HelpId, HelpId>,
141}
142
143impl Default for HelpRegistry {
144    fn default() -> Self {
145        Self::new()
146    }
147}
148
149impl HelpRegistry {
150    /// Create an empty registry.
151    #[must_use]
152    pub fn new() -> Self {
153        Self {
154            entries: HashMap::new(),
155            parents: HashMap::new(),
156        }
157    }
158
159    /// Register help content for a widget.
160    ///
161    /// Overwrites any previous content (or lazy provider) for the same ID.
162    pub fn register(&mut self, id: HelpId, content: HelpContent) {
163        self.entries.insert(id, Entry::Loaded(content));
164    }
165
166    /// Register a lazy provider that will be called on first lookup.
167    ///
168    /// The provider is invoked at most once; its result is cached.
169    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    /// Remove help content for a widget.
178    ///
179    /// Returns `true` if content was present.
180    pub fn unregister(&mut self, id: HelpId) -> bool {
181        self.entries.remove(&id).is_some()
182    }
183
184    /// Set the parent of a widget in the help hierarchy.
185    ///
186    /// When [`resolve`](Self::resolve) is called for `child` and no content
187    /// is found, the lookup walks to `parent` (and its ancestors).
188    ///
189    /// Returns `false` (and does nothing) if setting this parent would create
190    /// a cycle.
191    pub fn set_parent(&mut self, child: HelpId, parent: HelpId) -> bool {
192        // Cycle check: walk from parent upward; if we reach child, it's a cycle.
193        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    /// Remove the parent link for a widget.
208    pub fn clear_parent(&mut self, child: HelpId) {
209        self.parents.remove(&child);
210    }
211
212    /// Get help content for a specific widget (no hierarchy walk).
213    ///
214    /// Forces lazy providers if present.
215    #[must_use = "use the returned help content (if any)"]
216    pub fn get(&mut self, id: HelpId) -> Option<&HelpContent> {
217        // Force lazy → loaded if needed.
218        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    /// Peek at help content without forcing lazy providers.
231    #[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    /// Resolve help content by walking the parent hierarchy.
240    ///
241    /// Returns the first content found starting from `id` and walking up
242    /// through parents. Returns `None` if no content exists in the chain.
243    #[must_use = "use the returned help content (if any)"]
244    pub fn resolve(&mut self, id: HelpId) -> Option<&HelpContent> {
245        // Collect the chain of IDs to check (avoid borrow issues).
246        let chain = self.ancestor_chain(id);
247        // Force any lazy entries in the chain.
248        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        // Now find the first loaded entry.
257        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    /// Check whether any help content is registered for this ID (including lazy).
266    #[must_use]
267    pub fn contains(&self, id: HelpId) -> bool {
268        self.entries.contains_key(&id)
269    }
270
271    /// Number of registered entries (loaded + lazy).
272    #[inline]
273    #[must_use]
274    pub fn len(&self) -> usize {
275        self.entries.len()
276    }
277
278    /// Whether the registry is empty.
279    #[inline]
280    #[must_use]
281    pub fn is_empty(&self) -> bool {
282        self.entries.is_empty()
283    }
284
285    /// Iterate over all registered IDs.
286    pub fn ids(&self) -> impl Iterator<Item = HelpId> + '_ {
287        self.entries.keys().copied()
288    }
289
290    /// Build the ancestor chain starting from `id` (inclusive).
291    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    // ── Registration and lookup ────────────────────────────────────
316
317    #[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    // ── Lazy providers ─────────────────────────────────────────────
381
382    #[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()); // not yet forced
388        assert_eq!(reg.get(id).unwrap().short, "lazy");
389        assert!(reg.peek(id).is_some()); // now cached
390    }
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    // ── Hierarchy ──────────────────────────────────────────────────
411
412    #[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        // child has no content; resolve walks to grandparent
424        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        // child has no content; resolve finds parent first
440        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        // c → a would create cycle c→a→b→c
482        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    // ── Keybindings and structured content ─────────────────────────
500
501    #[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    // ── Lazy in hierarchy ──────────────────────────────────────────
539
540    #[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        // Now cached
551        assert!(reg.peek(parent).is_some());
552    }
553
554    // ── Edge cases ─────────────────────────────────────────────────
555
556    #[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        // Chain: 0 → 1 → 2 → 3 → 4 (content at 4)
566        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        // Reparent
587        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        // Remove parent content; resolve should walk to grandparent
604        reg.unregister(parent);
605        assert_eq!(reg.resolve(child).unwrap().short, "grandparent");
606    }
607}