Update .github/workflows/documentation.yaml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

.github/copilot-instructions.md

@@ -0,0 +1,212 @@
+# FTXUI - Functional Terminal (X) User Interface
+
+FTXUI is a cross-platform C++ library for terminal-based user interfaces with a functional programming approach, inspired by React.
+
+**ALWAYS reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the information here.**
+
+## Working Effectively
+
+### Build System Setup and Commands
+- Bootstrap and build the repository:
+  ```bash
+  # Basic build (library only) - fast
+  cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+  cmake --build build --parallel $(nproc)
+  # Build time: ~30 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
+  
+  # Build with examples  
+  cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DFTXUI_BUILD_EXAMPLES=ON
+  cmake --build build --parallel $(nproc)
+  # Build time: ~70 seconds. NEVER CANCEL. Set timeout to 180+ seconds.
+  
+  # Build with examples and tests
+  cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DFTXUI_BUILD_EXAMPLES=ON -DFTXUI_BUILD_TESTS=ON
+  cmake --build build --parallel $(nproc)
+  # Build time: ~113 seconds (includes GoogleTest download). NEVER CANCEL. Set timeout to 300+ seconds.
+  ```
+
+- Alternative build with Ninja (faster):
+  ```bash
+  cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DFTXUI_BUILD_EXAMPLES=ON
+  ninja -C build
+  # Build time: ~62 seconds. NEVER CANCEL. Set timeout to 180+ seconds.
+  ```
+
+- Run unit tests:
+  ```bash
+  # Configure with tests enabled first, then:
+  cd build && ctest --output-on-failure
+  # Test time: ~4 seconds (302 tests). NEVER CANCEL. Set timeout to 60+ seconds.
+  ```
+
+### Bazel Support
+- FTXUI also supports Bazel build system
+- **WARNING**: Bazel may fail due to network connectivity issues in sandboxed environments
+- If Bazel is available:
+  ```bash
+  bazel build //...  # Build everything
+  bazel test //...   # Run tests
+  ```
+
+## Validation
+
+### Manual Testing After Changes
+- **ALWAYS manually validate changes by building and running examples after making code modifications**
+- Run example applications to verify functionality:
+  ```bash
+  # Build an example first
+  cmake --build build --target ftxui_example_border
+  
+  # Run examples (they are interactive, use timeout to terminate)
+  timeout 2s build/examples/dom/ftxui_example_border
+  timeout 2s build/examples/dom/ftxui_example_color_gallery
+  timeout 2s build/examples/component/ftxui_example_button
+  ```
+- Examples should produce visual terminal output with borders, colors, and UI components
+- **CRITICAL**: Always run at least one DOM example and one Component example to verify both modules work
+
+### Code Quality and Formatting
+- Always run formatting before committing:
+  ```bash
+  ./tools/format.sh
+  # Format time: ~7 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
+  ```
+- The format script adds license headers and runs clang-format on all source files
+- **Required**: Run formatting or the CI (.github/workflows/build.yaml) will fail
+
+### Build Validation Requirements
+- ALWAYS build with both `-DFTXUI_BUILD_EXAMPLES=ON` and `-DFTXUI_BUILD_TESTS=ON` when making changes
+- Run the complete test suite with `ctest --output-on-failure`
+- All 302 tests must pass
+- **Scenario Testing**: Run at least these validation scenarios:
+  1. Build library only (basic validation)
+  2. Build with examples and run 2-3 different examples
+  3. Build with tests and run complete test suite
+  4. Run formatting tool to ensure code style compliance
+
+## Project Structure
+
+### Key Directories
+```
+/home/runner/work/FTXUI/FTXUI/
+├── include/ftxui/           # Public header files
+│   ├── component/           # Interactive component headers
+│   ├── dom/                 # DOM element headers  
+│   ├── screen/              # Screen and rendering headers
+│   └── util/                # Utility headers
+├── src/ftxui/               # Implementation files
+│   ├── component/           # Interactive components (buttons, menus, etc.)
+│   ├── dom/                 # DOM elements (layout, styling, text)
+│   ├── screen/              # Screen rendering and terminal handling
+│   └── util/                # Utilities
+├── examples/                # Example applications
+│   ├── component/           # Interactive component examples
+│   └── dom/                 # DOM element examples
+├── cmake/                   # CMake configuration files
+├── tools/                   # Development tools (formatting, etc.)
+└── .github/workflows/       # CI/CD configuration
+```
+
+### Core Library Modules
+FTXUI is organized into three main modules that depend on each other:
+```
+┌component──┐  (Interactive UI components)
+│┌dom──────┐│  (Layout and styling elements)  
+││┌screen─┐││  (Terminal rendering and input)
+└┴┴───────┴┴┘
+```
+
+1. **screen**: Low-level terminal handling, colors, pixels, input
+2. **dom**: Layout elements (hbox, vbox, text, borders, etc.)
+3. **component**: Interactive components (buttons, menus, input fields)
+
+### CMake Build Options
+| Option                            | Description                      | Default |
+|-----------------------------------|----------------------------------|---------|
+| FTXUI_BUILD_EXAMPLES              | Build example applications       | OFF     |
+| FTXUI_BUILD_DOCS                  | Build documentation             | OFF     |  
+| FTXUI_BUILD_TESTS                 | Build and enable tests          | OFF     |
+| FTXUI_BUILD_MODULES               | Build C++20 modules             | OFF     |
+| FTXUI_ENABLE_INSTALL              | Generate install targets        | ON      |
+| FTXUI_MICROSOFT_TERMINAL_FALLBACK | Windows terminal compatibility  | ON/OFF  |
+
+## Common Tasks
+
+### Building Examples
+```bash
+# Build specific examples
+cmake --build build --target ftxui_example_border
+cmake --build build --target ftxui_example_button
+cmake --build build --target ftxui_example_menu
+
+# List all available examples
+find build -name "ftxui_example_*" -type f
+```
+
+### Running Tests
+```bash
+# Run all tests
+cd build && ctest
+
+# Run tests with verbose output
+cd build && ctest --verbose
+
+# Run specific test pattern
+cd build && ctest -R "Button" --verbose
+```
+
+### Working with Source Code
+- **Component Development**: Modify files in `src/ftxui/component/` for interactive elements
+- **DOM Development**: Modify files in `src/ftxui/dom/` for layout and styling
+- **Screen Development**: Modify files in `src/ftxui/screen/` for terminal rendering
+- **Adding Examples**: Add new `.cpp` files in `examples/component/` or `examples/dom/`
+- **Header Files**: Public APIs are in `include/ftxui/[module]/`
+
+### Integration Patterns
+When adding FTXUI to a project, use CMake FetchContent (recommended):
+```cmake
+include(FetchContent)
+FetchContent_Declare(ftxui
+  GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui
+  GIT_TAG v6.1.9
+)
+FetchContent_MakeAvailable(ftxui)
+
+target_link_libraries(your_target PRIVATE
+    ftxui::component  # For interactive components
+    ftxui::dom        # For layout elements  
+    ftxui::screen     # For basic rendering
+)
+```
+
+## Troubleshooting
+
+### Build Issues
+- If CMake configuration fails, ensure C++20 support: `cmake --version` (need 3.12+)
+- If Ninja build fails, fall back to Make: `cmake -S . -B build` (without `-G Ninja`)
+- If tests fail to build, GoogleTest download might have failed - check network connectivity
+- Build artifacts are in `build/` directory - delete with `rm -rf build` to clean
+
+### Example Issues  
+- Examples are interactive terminal applications - use `timeout` to terminate them
+- If examples don't display correctly, terminal might not support colors/Unicode
+- Examples require terminal size of at least 80x24 for proper display
+
+### Formatting Issues
+- Format script requires clang-format to be installed
+- If format script fails, check that source files are not read-only
+- Format script modifies files in-place - commit changes afterwards
+
+## Critical Reminders
+
+- **NEVER CANCEL long-running builds** - they may take 2-3 minutes
+- **ALWAYS run the formatting tool** before committing changes  
+- **ALWAYS build and test examples** when making component/dom changes
+- **SET APPROPRIATE TIMEOUTS**: 300+ seconds for builds, 60+ seconds for tests
+- **BUILD TIMING EXPECTATIONS**:
+  - Basic library: ~30 seconds
+  - With examples: ~70 seconds  
+  - With examples + tests: ~113 seconds (first time, includes GoogleTest download)
+  - Subsequent builds: ~60-70 seconds
+  - Tests execution: ~4 seconds
+  - Formatting: ~7 seconds

.github/workflows/documentation.yaml

@@ -12,6 +12,10 @@ jobs:
     steps:
       - name: "Checkout repository"
         uses: actions/checkout@v3
+        with:
+          fetch-depth: 0   # Need full history.
+          fetch-tags: true # Need tags.
+
 
       - name: "Install cmake"
         uses: lukka/get-cmake@latest
@@ -30,19 +34,23 @@ jobs:
           sudo apt-get install graphviz;
 
       - name: "Build documentation"
+        run: |
+          python3 ./tools/build_multiversion_doc.py
+
+      - name: "Build examples"
         run: >
+          mkdir -p multiversion_docs/main/examples;
           mkdir build;
           cd build;
           emcmake cmake ..
           -DCMAKE_BUILD_TYPE=Release
-          -DFTXUI_BUILD_DOCS=ON
+          -DFTXUI_BUILD_DOCS=OFF
           -DFTXUI_BUILD_EXAMPLES=ON
           -DFTXUI_BUILD_TESTS=OFF
           -DFTXUI_BUILD_TESTS_FUZZER=OFF
           -DFTXUI_ENABLE_INSTALL=OFF
           -DFTXUI_DEV_WARNINGS=OFF;
           cmake --build . --target doc;
-          cmake --build . ;
           rsync -amv
           --include='*/'
           --include='*.html'
@@ -52,13 +60,13 @@ jobs:
           --include='*.wasm'
           --exclude='*'
           examples
-          doc/doxygen/html;
+          ../multiversion_docs/main/examples;
 
       - name: "Deploy"
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: build/doc/doxygen/html/
+          publish_dir: multiversion_docs
           enable_jekyll: false
           allow_empty_commit: false
           force_orphan: true

.gitignore

@@ -28,6 +28,7 @@ out/
 # .github directory:
 !.github/**/*.yaml
 !.github/**/*.yml
+!.github/**/*.md
 
 # cmake directory:
 !cmake/**/*.in
@@ -69,4 +70,6 @@ out/
 
 # tools directory:
 !tools/**/*.sh
+!tools/**/*.py
 !tools/**/*.cpp
+build/

BUILD.bazel

@@ -169,13 +169,15 @@ ftxui_cc_library(
         "src/ftxui/component/util.cpp",
         "src/ftxui/component/window.cpp",
 
-
         # Private header from ftxui:dom.
         "src/ftxui/dom/node_decorator.hpp",
 
         # Private header from ftxui:screen.
         "src/ftxui/screen/string_internal.hpp",
         "src/ftxui/screen/util.hpp",
+
+        # Private header.
+        "include/ftxui/util/warn_windows_macro.hpp",
     ],
     hdrs = [
         "include/ftxui/component/animation.hpp",

CHANGELOG.md

@@ -29,6 +29,8 @@ Next
 ### Component
 - Fix ScreenInteractive::FixedSize screen stomps on the preceding terminal
   output. Thanks @zozowell in #1064.
+- Fix vertical `ftxui::Slider`. The "up" key was previously decreasing the
+  value. Thanks @its-pablo in #1093 for reporting the issue.
 
 
 6.1.9 (2025-05-07)

CMakeLists.txt

@@ -178,8 +178,8 @@ include(cmake/ftxui_install.cmake)
 include(cmake/ftxui_package.cmake)
 include(cmake/ftxui_modules.cmake)
 
-add_subdirectory(doc)
 add_subdirectory(examples)
+add_subdirectory(doc)
 
 # You can generate ./examples_modules/ by running
 # ./tools/generate_examples_modules.sh

README.md

@@ -1,3 +1,4 @@
+
 <p align="center">
   <img src="https://github.com/ArthurSonzogni/FTXUI/assets/4759106/6925b6da-0a7e-49d9-883c-c890e1f36007" alt="Demo image"></img>
   <br/>
@@ -362,6 +363,8 @@ Feel free to add your projects here:
 - [FTB - tertminal file browser](https://github.com/Cyxuan0311/FTB)
 - [openJuice](https://github.com/mikomikotaishi/openJuice)
 - [SHOOT!](https://github.com/ShingZhanho/ENGG1340-Project-25Spring)
+- [VerifySN (Fast Hash Tool)](https://github.com/d06i/verifySN)
+- [tic-tac-toe](https://github.com/birland/tic-tac-toe)
 
 ### [cpp-best-practices/game_jam](https://github.com/cpp-best-practices/game_jam)
 

doc/footer.html

@@ -2,16 +2,9 @@
 <!-- start footer part -->
 <!--BEGIN GENERATE_TREEVIEW-->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
-  <ul>
-    $navpath
-    <li class="footer">$generatedby <a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion </li>
-  </ul>
 </div>
 <!--END GENERATE_TREEVIEW-->
 <!--BEGIN !GENERATE_TREEVIEW-->
-<hr class="footer"/><address class="footer"><small>
-$generatedby&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="$relpath^doxygen.svg" width="104" height="31" alt="doxygen"/></a> $doxygenversion
-</small></address>
 <!--END !GENERATE_TREEVIEW-->
 </body>
 </html>

doc/installation_conan.md

@@ -1,24 +1,104 @@
 @page installation_conan Conan
+@tableofcontents
 
-Unofficial recipe for FTXUI exists on Conan Center:
-<https://conan.io/center/recipes/ftxui>
+FTXUI can be easily obtained and integrated into your project using the Conan package manager.
+
+## Prerequisites
+
+First, ensure that Conan is installed on your system. If not, you can install it via pip:
+
+```powershell
+pip install conan
+```
+Conan often works in tandem with CMake, so you will need to have CMake installed as well. Once you have confirmed both Conan and CMake are installed, create a project directory, for example, `ftxui-demo`:
+
+```powershell
+mkdir C:\ftxui-demo
+cd C:\ftxui-demo
+```
+
+## Configuration
+
+After ensuring your environment is set up correctly, create a Conan configuration file `conanfile.txt`. This file is used to declare your project's dependencies. The community-maintained package for FTXUI can be found on [Conan Center](https://conan.io/center/recipes/ftxui).
 
 > [!note]
-> This is an unofficial recipe. That means it is not maintained by the FTXUI
-> team, but by the community. The package maintainers seems to actively update
-> the package to the latest version. Thanks to the maintainers for their work!
+> This is an unofficial build script. This means it is not maintained by the FTXUI
+> team but by the community. The package maintainer appears to actively update it
+> to the latest releases. Many thanks to the maintainer for their work!
 
+@todo If you are familiar with the process, please consider adding an "official" build script to Conan Center.
+This could be a GitHub Action that automatically updates Conan Center upon new releases.
 
-@todo Add instructions on how to use the conan recipe.
+```ini
+[requires]
+ftxui/6.0.2
 
-@todo Please consider adding an "official" recipe to Conan Center if know how.
-It could be a github action that will automatically update the conan center
-when a new release is made.
+[generators]
+CMakeDeps
+CMakeToolchain
+
+[layout]
+cmake_layout
+```
+
+## Install Dependencies and Build
+
+Once configured, run the following command to install FTXUI and its dependencies:
+
+```powershell
+conan install . --output-folder=build --build=missing
+```
+
+This will download and install `ftxui/6.0.2` along with all its dependencies from Conan's remote repositories.
+
+After the installation completes, you can test it by creating a `demo.cpp` file in your project directory:
+
+```cpp
+#include <ftxui/screen/screen.hpp>
+#include <ftxui/dom/elements.hpp>
+#include <iostream>
+
+int main() {
+    using namespace ftxui;
+    auto document = hbox({
+        text(" Hello "),
+        text("FTXUI ") | bold | color(Color::Red),
+        text(" world! ")
+    });
+    auto screen = Screen::Create(Dimension::Full(), Dimension::Fit(document));
+    Render(screen, document);
+    std::cout << screen.ToString() << std::endl;
+    return 0;
+}
+```
+
+If the test is successful, you can then create a `CMakeLists.txt` file in the project directory:
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project(ftxui-demo)
+
+# Set the C++ standard
+set(CMAKE_CXX_STANDARD 20)
+
+# Find the FTXUI package installed via Conan
+find_package(ftxui CONFIG REQUIRED)
+
+# Create the executable
+add_executable(demo demo.cpp)
+
+# Link the executable to the FTXUI library
+target_link_libraries(demo PRIVATE ftxui::component)
+```
+
+@todo 考虑到中国多数地区使用Conan很有可能遇到各种网络问题，我想做一个定制的版本说明，但是我对conan的了解有限再加上没有找到合适的资料，因此这个计划短暂的被搁置了，如果您知道方法，欢迎在[中文版本](xiaoditx.girhub.io/public/docs/ftxui%E4%B8%AD%E6%96%87%E7%BF%BB%E8%AF%91/installation/conan/)的下方留下评论以提醒我
+
+---
 
 <div class="section_buttons">
- 
+
 | Previous          |
 |:------------------|
 | [Getting Started](getting-started.html) |
- 
-</div>
+
+</div>

examples/CMakeLists.txt

@@ -17,10 +17,12 @@ add_subdirectory(dom)
 if (EMSCRIPTEN)
   get_property(EXAMPLES GLOBAL PROPERTY FTXUI::EXAMPLES)
   foreach(file
+      "index.css"
       "index.html"
       "index.mjs"
-      "index.css"
-      "run_webassembly.py")
+      "run_webassembly.py"
+      "sw.js"
+  )
     configure_file(${file} ${file})
   endforeach(file)
 endif()

examples/component/button.cpp

@@ -34,8 +34,8 @@ int main() {
   int value = 50;
 
   // clang-format off
-  auto btn_dec_01 = Button("-1", [&] { value += 1; }, Style());
-  auto btn_inc_01 = Button("+1", [&] { value -= 1; }, Style());
+  auto btn_dec_01 = Button("-1", [&] { value -= 1; }, Style());
+  auto btn_inc_01 = Button("+1", [&] { value += 1; }, Style());
   auto btn_dec_10 = Button("-10", [&] { value -= 10; }, Style());
   auto btn_inc_10 = Button("+10", [&] { value += 10; }, Style());
   // clang-format on

examples/index.css

@@ -1,15 +1,19 @@
 @import url(https://fonts.googleapis.com/css?family=Khula:700);
 
+html {
+  --toc-width: 250px;
+}
+
 body {
-  background-color:#EEE;
-  padding:0px;
-  margin:0px;
+  background-color: #EEE;
+  padding: 0px;
+  margin: 0px;
   font-family: Khula, Helvetica, sans-serif;
   font-size: 130%;
 }
 
 .page {
-  max-width:1300px;
+  max-width: 1300px;
   margin: auto;
   padding: 10px;
 }
@@ -20,7 +24,7 @@ a {
   margin: 0 -.25rem;
   padding: 0 .25rem;
   transition: color .3s ease-in-out,
-              box-shadow .3s ease-in-out;
+    box-shadow .3s ease-in-out;
 }
 
 a:hover {
@@ -30,45 +34,48 @@ a:hover {
 
 h1 {
   text-decoration: underline;
-  width:100%;
-  background-color: rgba(100,100,255,0.5);
+  width: 100%;
+  background-color: rgba(100, 100, 255, 0.5);
   padding: 10px;
   margin: 0;
 }
 
 
 #selectExample {
-  flex:1;
+  flex: 1;
 }
 
-#selectExample, #selectExample option {
+#selectExample,
+#selectExample option {
   font-size: 16px;
   font-family: sans-serif;
   font-weight: 700;
   line-height: 1.3;
-  border:0px;
+  border: 0px;
   background-color: #bbb;
-  color:black;
+  color: black;
 }
 
 #selectExample:focus {
-  outline:none;
+  outline: none;
 }
 
 #terminal {
-  width:100%;
+  width: 100%;
   height 500px;
   height: calc(clamp(200px, 100vh - 300px, 900px));
   overflow: hidden;
-  border:none;
-  background-color:black;
+  border: none;
+  padding: 10px;
+  margin: 10px;
 }
 
 #terminalContainer {
   overflow: hidden;
   border-radius: 10px;
-  box-shadow: 0px 2px 10px 0px rgba(0,0,0,0.75),
-  0px 2px 80px 0px rgba(0,0,0,0.50);
+  box-shadow: 0px 2px 10px 0px rgba(0, 0, 0, 0.75),
+    0px 2px 80px 0px rgba(0, 0, 0, 0.50);
+  background-color: black;
 }
 
 .fakeButtons {
@@ -76,7 +83,7 @@ h1 {
   width: 10px;
   border-radius: 50%;
   border: 1px solid #000;
-  margin:6px;
+  margin: 6px;
   background-color: #ff3b47;
   border-color: #9d252b;
   display: inline-block;
@@ -95,13 +102,79 @@ h1 {
 }
 
 .fakeMenu {
-  display:flex;
+  display: flex;
   flex-direction: row;
-  width:100%;
+  width: 100%;
   box-sizing: border-box;
   height: 25px;
   background-color: #bbb;
-  color:black;
+  color: black;
   margin: 0 auto;
   overflow: hidden;
 }
+
+.toc-container {
+  position: fixed;
+  left: 0;
+  top: 0;
+  bottom: 0;
+  width: var(--toc-width);
+  background: white;
+  padding: 0;
+  overflow-y: auto;
+  overflow-x: hidden;
+  scrollbar-width: thin;
+}
+
+.toc-title {
+  font-weight: bold;
+  margin-bottom: 5px;
+  font-size: 0.9em;
+  color: #555;
+
+  position: sticky;
+  transition: position 1.0s ease-in-out;
+  top: 0;
+  z-index: 1;
+  padding: 20px;
+  margin: 0;
+
+  border-bottom: 1px solid #ddd;
+
+  /* Gradient background for the title */
+  background-color: #f0f0f0;
+}
+
+.toc-item {
+  padding: 3px 8px;
+  margin: 0;
+  cursor: pointer;
+  font-size: 0.85em;
+  border-radius: 3px;
+  transition: background 0.2s;
+}
+
+.toc-item:hover {
+  background: #f0f0f0;
+}
+
+.toc-item.selected {
+  background: #e0e0e0;
+  font-weight: bold;
+}
+
+@media (max-width: 1024px) {
+  .toc-container {
+    display: none;
+  }
+
+  .page {
+    margin-left: 0;
+  }
+}
+
+@media (min-width: 1025px) {
+  .page {
+    margin-left: calc(var(--toc-width) + 20px);
+  }
+}

examples/index.html

@@ -9,13 +9,18 @@
     <script type="module" src="index.mjs"></script>
   </head>
   <body>
+    <div class="toc-container">
+      <div class="toc-list"></div>
+    </div>
     <script id="example_script"></script>
 
     <div class="page">
       <p>
         <a href="https://github.com/ArthurSonzogni/FTXUI">FTXUI</a> is a simple
         functional C++ library for terminal user interface. <br/>
-        This showcases the: <a href="https://github.com/ArthurSonzogni/FTXUI/tree/master/examples">./example/</a> folder. <br/>
+        This showcases the: <a
+          href="https://github.com/ArthurSonzogni/FTXUI/tree/master/examples">./example/</a>
+        folder. See <a id="source">source</a>.
       </p>
 
       <div id="terminalContainer">

examples/index.mjs

@@ -92,6 +92,69 @@ window.Module = {
   },
 };
 
+const source = document.querySelector("#source");
+source.href = "https://github.com/ArthurSonzogni/FTXUI/blob/main/examples/" + example + ".cpp";
+
 const words = example.split('/')
 words[1] = "ftxui_example_" + words[1] + ".js"
 document.querySelector("#example_script").src = words.join('/');
+
+
+// Table of Contents (TOC) for quick navigation.
+
+// Get select element
+const selectEl = document.querySelector('select#selectExample');
+if (!selectEl) {
+  console.error('select#selectExample not found');
+} else {
+  // Get TOC container
+  const tocContainer = document.querySelector('.toc-container');
+  const tocList = tocContainer.querySelector('.toc-list');
+
+  // Group options by directory
+  const groupedOptions = Array.from(selectEl.options).reduce((acc, option) => {
+    const [dir, file] = option.text.split('/');
+    if (!acc[dir]) {
+      acc[dir] = [];
+    }
+    acc[dir].push({ option, file });
+    return acc;
+  }, {});
+
+  // Generate TOC items
+  for (const dir in groupedOptions) {
+    const dirContainer = document.createElement('div');
+
+    const dirHeader = document.createElement('div');
+    dirHeader.textContent = dir;
+    dirHeader.className = 'toc-title';
+    dirContainer.appendChild(dirHeader);
+
+    groupedOptions[dir].forEach(({ option, file }) => {
+      const tocItem = document.createElement('div');
+      tocItem.textContent = file;
+      tocItem.className = 'toc-item';
+
+      if (selectEl.options[selectEl.selectedIndex].value === option.value) {
+        tocItem.classList.add('selected');
+      }
+
+      // Click handler
+      tocItem.addEventListener('click', () => {
+        for(let i=0; i<selectEl.options.length; ++i) {
+          if (selectEl.options[i].value == option.value) {
+            selectEl.selectedIndex = i;
+            break;
+          }
+        }
+
+        history.pushState({}, "", "?file=" + option.value);
+        location.reload();
+      });
+
+      dirContainer.appendChild(tocItem);
+    });
+
+    tocList.appendChild(dirContainer);
+  }
+}''

include/ftxui/component/receiver.hpp

@@ -4,14 +4,14 @@
 #ifndef FTXUI_COMPONENT_RECEIVER_HPP_
 #define FTXUI_COMPONENT_RECEIVER_HPP_
 
-#include <ftxui/util/warn_windows_macro.h>
 #include <algorithm>           // for copy, max
 #include <atomic>              // for atomic, __atomic_base
 #include <condition_variable>  // for condition_variable
-#include <memory>              // for unique_ptr, make_unique
-#include <mutex>               // for mutex, unique_lock
-#include <queue>               // for queue
-#include <utility>             // for move
+#include <ftxui/util/warn_windows_macro.hpp>
+#include <memory>   // for unique_ptr, make_unique
+#include <mutex>    // for mutex, unique_lock
+#include <queue>    // for queue
+#include <utility>  // for move
 
 namespace ftxui {
 

include/ftxui/screen/screen.hpp

@@ -60,7 +60,7 @@ class Screen : public Image {
       BarBlinking = 5,
       Bar = 6,
     };
-    Shape shape;
+    Shape shape = Hidden;
   };
 
   Cursor cursor() const { return cursor_; }

src/ftxui/component/slider.cpp

@@ -33,6 +33,20 @@ Decorator flexDirection(Direction direction) {
   return xflex;  // NOT_REACHED()
 }
 
+Direction Opposite(Direction d) {
+  switch (d) {
+    case Direction::Up:
+      return Direction::Down;
+    case Direction::Down:
+      return Direction::Up;
+    case Direction::Left:
+      return Direction::Right;
+    case Direction::Right:
+      return Direction::Left;
+  }
+  return d;  // NOT_REACHED()
+}
+
 template <class T>
 class SliderBase : public SliderOption<T>, public ComponentBase {
  public:
@@ -47,59 +61,15 @@ class SliderBase : public SliderOption<T>, public ComponentBase {
            flexDirection(this->direction) | reflect(gauge_box_) | gauge_color;
   }
 
-  void OnLeft() {
-    switch (this->direction) {
-      case Direction::Right:
-        this->value() -= this->increment();
-        break;
-      case Direction::Left:
-        this->value() += this->increment();
-        break;
-      case Direction::Up:
-      case Direction::Down:
-        break;
+  void OnDirection(Direction pressed) {
+    if (pressed == this->direction) {
+      this->value() += this->increment();
+      return;
     }
-  }
 
-  void OnRight() {
-    switch (this->direction) {
-      case Direction::Right:
-        this->value() += this->increment();
-        break;
-      case Direction::Left:
-        this->value() -= this->increment();
-        break;
-      case Direction::Up:
-      case Direction::Down:
-        break;
-    }
-  }
-
-  void OnUp() {
-    switch (this->direction) {
-      case Direction::Up:
-        this->value() -= this->increment();
-        break;
-      case Direction::Down:
-        this->value() += this->increment();
-        break;
-      case Direction::Left:
-      case Direction::Right:
-        break;
-    }
-  }
-
-  void OnDown() {
-    switch (this->direction) {
-      case Direction::Down:
-        this->value() += this->increment();
-        break;
-      case Direction::Up:
-        this->value() -= this->increment();
-        break;
-      case Direction::Left:
-      case Direction::Right:
-        break;
+    if (pressed == Opposite(this->direction)) {
+      this->value() -= this->increment();
+      return;
     }
   }
 
@@ -110,16 +80,16 @@ class SliderBase : public SliderOption<T>, public ComponentBase {
 
     T old_value = this->value();
     if (event == Event::ArrowLeft || event == Event::Character('h')) {
-      OnLeft();
+      OnDirection(Direction::Left);
     }
     if (event == Event::ArrowRight || event == Event::Character('l')) {
-      OnRight();
+      OnDirection(Direction::Right);
     }
     if (event == Event::ArrowUp || event == Event::Character('k')) {
-      OnDown();
+      OnDirection(Direction::Up);
     }
     if (event == Event::ArrowDown || event == Event::Character('j')) {
-      OnUp();
+      OnDirection(Direction::Down);
     }
 
     this->value() = std::max(this->min(), std::min(this->max(), this->value()));

src/ftxui/component/task_runner.hpp

@@ -21,8 +21,8 @@ class TaskRunner {
   auto PostTask(Task task) -> void;
 
   /// Schedules a task to be executed after a certain duration.
-  auto PostDelayedTask(Task task, std::chrono::steady_clock::duration duration)
-      -> void;
+  auto PostDelayedTask(Task task,
+                       std::chrono::steady_clock::duration duration) -> void;
 
   /// Runs the tasks in the queue, return the delay until the next delayed task
   /// can be executed.

src/ftxui/dom/size.cpp

@@ -81,7 +81,7 @@ class Size : public Node {
 }  // namespace
 
 /// @brief Apply a constraint on the size of an element.
-/// @param direction Whether the WIDTH of the HEIGHT of the element must be
+/// @param direction Whether the WIDTH or the HEIGHT of the element must be
 ///                  constrained.
 /// @param constraint The type of constaint.
 /// @param value The value.

tools/build_multiversion_doc.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+
+import os
+import subprocess
+import shutil
+import tempfile
+import json
+from pathlib import Path
+from typing import List, Dict
+
+class VersionInfo:
+    """A structure to hold all information about a single documentation version."""
+    def __init__(self, name: str, is_main: bool, output_root: Path):
+        self.name = name
+        self.is_main = is_main
+        # Destination directory for the built docs, relative to the output root.
+        self.dest_dir = output_root if is_main else output_root / "en" / name
+        # The path to this version's index.html, relative to the output root.
+        self.index_path_from_root = self.dest_dir / "index.html"
+
+    def __repr__(self) -> str:
+        return f"VersionInfo(name='{self.name}', dest_dir='{self.dest_dir}')"
+
+def run_command(command: List[str], check: bool = True, cwd: Path = None):
+    """
+    Runs a command, prints its output, and handles errors.
+    """
+    command_str = ' '.join(command)
+    print(f"Executing: {command_str} in {cwd or Path.cwd()}")
+    try:
+        # Using capture_output=True to get stdout/stderr
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            check=check,
+            cwd=cwd
+        )
+        if result.stdout:
+            print(result.stdout)
+        if result.stderr:
+            print(result.stderr)
+        return result
+    except subprocess.CalledProcessError as e:
+        print(f"ERROR: Command failed with exit code {e.returncode}")
+        print(f"Command: {command_str}")
+        if e.stdout:
+            print("--- STDOUT ---")
+            print(e.stdout)
+        if e.stderr:
+            print("--- STDERR ---")
+            print(e.stderr)
+        raise  # Re-raise the exception to halt the script
+
+def get_version_switcher_js(
+    current_version: VersionInfo,
+    all_versions: List[VersionInfo],
+    current_html_file: Path
+) -> str:
+    """
+    Generates the JavaScript for the version switcher dropdown.
+
+    This version pre-calculates the relative path from the current HTML file
+    to the index.html of every other version, simplifying the JS logic.
+    """
+    version_names = [v.name for v in all_versions]
+
+    # Create a dictionary mapping version names to their relative URLs.
+    relative_paths: Dict[str, str] = {}
+    for version in all_versions:
+        # Calculate the relative path from the *parent directory* of the current HTML file
+        # to the target version's index.html.
+        path = os.path.relpath(version.index_path_from_root, current_html_file.parent)
+        relative_paths[version.name] = path
+
+    # Use json.dumps for safe serialization of data into JavaScript.
+    versions_json = json.dumps(version_names)
+    paths_json = json.dumps(relative_paths)
+    current_version_json = json.dumps(current_version.name)
+
+    return f"""
+document.addEventListener('DOMContentLoaded', function() {{
+  const projectNumber = document.getElementById('projectnumber');
+  if (!projectNumber) {{
+    console.warn('Doxygen element with ID "projectnumber" not found. Cannot add version switcher.');
+    return;
+  }}
+
+  const versions = {versions_json};
+  const version_paths = {paths_json};
+  const currentVersion = {current_version_json};
+
+  // Sort versions: 'main' first, then others numerically descending.
+  versions.sort((a, b) => {{
+    if (a === 'main') return -1;
+    if (b === 'main') return 1;
+    return b.localeCompare(a, undefined, {{ numeric: true, sensitivity: 'base' }});
+  }});
+
+  const select = document.createElement('select');
+  select.onchange = function() {{
+    const selectedVersion = this.value;
+    // Navigate directly to the pre-calculated relative path.
+    if (selectedVersion !== currentVersion) {{
+      window.location.href = version_paths[selectedVersion];
+    }}
+  }};
+
+  versions.forEach(v => {{
+    const option = document.createElement('option');
+    option.value = v;
+    option.textContent = v;
+    if (v === currentVersion) {{
+      option.selected = true;
+    }}
+    select.appendChild(option);
+  }});
+
+  // Replace the Doxygen project number element with our dropdown.
+  projectNumber.replaceWith(select);
+
+  // Apply some styling to make it look good.
+  Object.assign(select.style, {{
+    backgroundColor: 'rgba(0, 0, 0, 0.8)',
+    color: 'white',
+    border: '1px solid rgba(255, 255, 255, 0.2)',
+    padding: '5px',
+    borderRadius: '5px',
+    fontSize: '14px',
+    fontFamily: 'inherit',
+    marginLeft: '10px',
+    cursor: 'pointer'
+  }});
+}});
+"""
+
+def main():
+    """Main function to build multi-version documentation."""
+    root_dir = Path.cwd()
+    output_dir = root_dir / "multiversion_docs"
+
+    print("--- 1. Cleaning up old documentation ---")
+    if output_dir.exists():
+        shutil.rmtree(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    print("--- 2. Getting versions from git ---")
+    git_tags_result = run_command(["git", "tag", "--list", "v*"])
+    # Create a list of version names, starting with 'main'.
+    version_names = ["main"] + sorted(
+        git_tags_result.stdout.splitlines(),
+        reverse=True
+    )
+    # For demonstration, limit the number of versions. Remove this in production.
+    version_names = version_names[:4]
+    print(f"Versions to build: {', '.join(version_names)}")
+
+    # Pre-compute all version information and paths.
+    versions = [
+        VersionInfo(name, name == "main", output_dir)
+        for name in version_names
+    ]
+
+    with tempfile.TemporaryDirectory() as build_dir_str:
+        build_dir = Path(build_dir_str)
+        # --- 3. Build documentation for each version ---
+        for version in versions:
+            print(f"\n--- Building docs for version: {version.name} ---")
+
+            # Create a temporary directory for this version's source code.
+            version_src_dir = build_dir / f"src_{version.name}"
+            version_src_dir.mkdir()
+
+            # Check out the version's source code from git.
+            archive_path = version_src_dir / "source.tar"
+            run_command([
+                "git", "archive", version.name,
+                "--format=tar", f"--output={archive_path}"
+            ])
+            run_command(["tar", "-xf", str(archive_path)], cwd=version_src_dir)
+            archive_path.unlink()
+
+            # Configure and build the docs using CMake.
+            version_build_dir = build_dir / f"build_{version.name}"
+            version_build_dir.mkdir()
+            run_command([
+                "cmake", str(version_src_dir), "-DFTXUI_BUILD_DOCS=ON"
+            ], cwd=version_build_dir)
+            run_command(["make", "doc"], cwd=version_build_dir)
+
+            # Copy the generated HTML files to the final destination.
+            doxygen_html_dir = version_build_dir / "doc" / "doxygen" / "html"
+            if not doxygen_html_dir.is_dir():
+                print(f"FATAL: Doxygen HTML output not found for version {version.name}")
+                exit(1)
+
+            print(f"Copying files to: {version.dest_dir}")
+            shutil.copytree(doxygen_html_dir, version.dest_dir, dirs_exist_ok=True)
+
+    # --- 4. Inject version switcher into all HTML files ---
+    print("\n--- Injecting version switcher JavaScript ---")
+    for version in versions:
+        if not version.dest_dir.exists():
+            print(f"Warning: Destination directory for {version.name} does not exist. Skipping JS injection.")
+            continue
+        
+        print(f"Processing HTML files in: {version.dest_dir}")
+        for html_file in version.dest_dir.rglob("*.html"):
+            js_script = get_version_switcher_js(version, versions, html_file)
+            script_tag = f'<script>{js_script}</script>'
+
+            content = html_file.read_text(encoding='utf-8')
+            # Inject the script right before the closing body tag.
+            new_content = content.replace("</body>", f"{script_tag}\n</body>")
+            html_file.write_text(new_content, encoding='utf-8')
+
+    print("\n--- 5. Finalizing ---")
+    print("Multi-version documentation generated successfully!")
+    print(f"Output located in: {output_dir.resolve()}")
+
+if __name__ == "__main__":
+    main()