feat: implement PageStack class for multi-page navigation in LVGL apps

main/ui/page_stack.h

@@ -0,0 +1,86 @@
+#pragma once
+
+#include "lvgl.h"
+#include <vector>
+#include <functional>
+
+/**
+ * @brief Reusable page stack for multi-page navigation within LVGL apps
+ *
+ * Manages a stack of LVGL containers, allowing apps to push/pop pages
+ * and implement hierarchical navigation. Thread-safe for use with LVGL.
+ */
+class PageStack {
+public:
+    /**
+     * @brief Page builder callback
+     * @param page_container The LVGL container to build the page in
+     */
+    using PageBuilder = std::function<void(lv_obj_t* page_container)>;
+
+    /**
+     * @brief Page cleanup callback
+     * @param page_container The LVGL container being destroyed
+     */
+    using PageCleanup = std::function<void(lv_obj_t* page_container)>;
+
+    /**
+     * @brief Construct page stack with parent container
+     * @param parent_container Parent LVGL container for pages
+     */
+    explicit PageStack(lv_obj_t* parent_container);
+
+    /**
+     * @brief Destructor - clears all pages
+     */
+    ~PageStack();
+
+    /**
+     * @brief Push a new page onto the stack
+     * @param builder Function to build page content
+     * @param cleanup Optional cleanup function called when page is popped
+     * @return The created page container
+     */
+    lv_obj_t* push(PageBuilder builder, PageCleanup cleanup = nullptr);
+
+    /**
+     * @brief Pop the current page and return to previous
+     * @return true if page was popped, false if stack is empty
+     */
+    bool pop();
+
+    /**
+     * @brief Clear all pages from the stack
+     */
+    void clear();
+
+    /**
+     * @brief Get the current (top) page container
+     * @return Current page or nullptr if stack is empty
+     */
+    lv_obj_t* current_page() const;
+
+    /**
+     * @brief Get the number of pages in the stack
+     */
+    size_t depth() const { return pages_.size(); }
+
+    /**
+     * @brief Check if stack is empty
+     */
+    bool empty() const { return pages_.empty(); }
+
+private:
+    struct Page {
+        lv_obj_t* container;
+        PageCleanup cleanup;
+    };
+
+    lv_obj_t* parent_container_;
+    std::vector<Page> pages_;
+
+    /**
+     * @brief Create a page container
+     */
+    lv_obj_t* create_page_container();
+};