TabsManager.py Added unit tests + documentation

2025-12-07 15:42:48 +01:00
parent 05067515d6
commit fde2e85c92
11 changed files with 4375 additions and 317 deletions
--- a/docs/TabsManager.md
+++ b/docs/TabsManager.md
@@ -0,0 +1,622 @@
+# TabsManager Component
+
+## Introduction
+
+The TabsManager component provides a dynamic tabbed interface for organizing multiple views within your FastHTML application. It handles tab creation, activation, closing, and content management with automatic state persistence and HTMX-powered interactions.
+
+**Key features:**
+
+- Dynamic tab creation and removal at runtime
+- Automatic content caching for performance
+- Session-based state persistence (tabs, order, active tab)
+- Duplicate tab detection based on component identity
+- Built-in search menu for quick tab navigation
+- Auto-increment labels for programmatic tab creation
+- HTMX-powered updates without page reload
+
+**Common use cases:**
+
+- Multi-document editor (code editor, text editor)
+- Dashboard with multiple data views
+- Settings interface with different configuration panels
+- Developer tools with console, inspector, network tabs
+- Application with dynamic content sections
+
+## Quick Start
+
+Here's a minimal example showing a tabbed interface with three views:
+
+```python
+from fasthtml.common import *
+from myfasthtml.controls.TabsManager import TabsManager
+from myfasthtml.core.instances import RootInstance
+
+# Create root instance and tabs manager
+root = RootInstance(session)
+tabs = TabsManager(parent=root)
+
+# Create three tabs with different content
+tabs.create_tab("Dashboard", Div(H1("Dashboard"), P("Overview of your data")))
+tabs.create_tab("Settings", Div(H1("Settings"), P("Configure your preferences")))
+tabs.create_tab("Profile", Div(H1("Profile"), P("Manage your profile")))
+
+# Render the tabs manager
+return tabs
+```
+
+This creates a complete tabbed interface with:
+
+- A header bar displaying three clickable tab buttons ("Dashboard", "Settings", "Profile")
+- Close buttons (×) on each tab for dynamic removal
+- A main content area showing the active tab's content
+- A search menu (⊞ icon) for quick tab navigation when many tabs are open
+- Automatic HTMX updates when switching or closing tabs
+
+**Note:** Tabs are interactive by default. Users can click tab labels to switch views, click close buttons to remove tabs, or use the search menu to find tabs quickly. All interactions update the UI without page reload thanks to HTMX integration.
+
+## Basic Usage
+
+### Visual Structure
+
+The TabsManager component consists of a header with tab buttons and a content area:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  Tab Header                                                │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐          ┌────┐  │
+│  │ Tab 1  × │ │ Tab 2  × │ │ Tab 3  × │          │ ⊞  │  │
+│  └──────────┘ └──────────┘ └──────────┘          └────┘  │
+├────────────────────────────────────────────────────────────┤
+│                                                            │
+│                                                            │
+│                    Active Tab Content                      │
+│                                                            │
+│                                                            │
+└────────────────────────────────────────────────────────────┘
+```
+
+**Component details:**
+
+| Element           | Description                                      |
+|-------------------|--------------------------------------------------|
+| Tab buttons       | Clickable labels to switch between tabs         |
+| Close button (×)  | Removes the tab and its content                  |
+| Search menu (⊞)   | Dropdown menu to search and filter tabs          |
+| Content area      | Displays the active tab's content                |
+
+### Creating a TabsManager
+
+The TabsManager is a `MultipleInstance`, meaning you can create multiple independent tab managers in your application. Create it by providing a parent instance:
+
+```python
+tabs = TabsManager(parent=root_instance)
+
+# Or with a custom ID
+tabs = TabsManager(parent=root_instance, _id="my-tabs")
+```
+
+### Creating Tabs
+
+Use the `create_tab()` method to add a new tab:
+
+```python
+# Create a tab with custom content
+tab_id = tabs.create_tab(
+    label="My Tab",
+    component=Div(H1("Content"), P("Tab content here"))
+)
+
+# Create with a MyFastHtml control
+from myfasthtml.controls.VisNetwork import VisNetwork
+network = VisNetwork(parent=tabs, nodes=nodes_data, edges=edges_data)
+tab_id = tabs.create_tab("Network View", network)
+
+# Create without activating immediately
+tab_id = tabs.create_tab("Background Tab", content, activate=False)
+```
+
+**Parameters:**
+- `label` (str): Display text shown in the tab button
+- `component` (Any): Content to display in the tab (FastHTML elements or MyFastHtml controls)
+- `activate` (bool): Whether to make this tab active immediately (default: True)
+
+**Returns:** A unique `tab_id` (UUID string) that identifies the tab
+
+### Showing Tabs
+
+Use the `show_tab()` method to activate and display a tab:
+
+```python
+# Show a tab (makes it active and sends content to client if needed)
+tabs.show_tab(tab_id)
+
+# Show without activating (just send content to client)
+tabs.show_tab(tab_id, activate=False)
+```
+
+**Parameters:**
+- `tab_id` (str): The UUID of the tab to show
+- `activate` (bool): Whether to make this tab active (default: True)
+
+**Note:** The first time a tab is shown, its content is sent to the client and cached. Subsequent activations just toggle visibility without re-sending content.
+
+### Closing Tabs
+
+Use the `close_tab()` method to remove a tab:
+
+```python
+# Close a specific tab
+tabs.close_tab(tab_id)
+```
+
+**What happens when closing:**
+1. Tab is removed from the tab list and order
+2. Content is removed from cache and client
+3. If the closed tab was active, the first remaining tab becomes active
+4. If no tabs remain, `active_tab` is set to `None`
+
+### Changing Tab Content
+
+Use the `change_tab_content()` method to update an existing tab's content and label:
+
+```python
+# Update tab content and label
+new_content = Div(H1("Updated"), P("New content"))
+tabs.change_tab_content(
+    tab_id=tab_id,
+    label="Updated Tab",
+    component=new_content,
+    activate=True
+)
+```
+
+**Parameters:**
+- `tab_id` (str): The UUID of the tab to update
+- `label` (str): New label for the tab
+- `component` (Any): New content to display
+- `activate` (bool): Whether to activate the tab after updating (default: True)
+
+**Note:** This method forces the new content to be sent to the client, even if the tab was already displayed.
+
+## Advanced Features
+
+### Auto-increment Labels
+
+When creating multiple tabs programmatically, you can use auto-increment to generate unique labels:
+
+```python
+# Using the on_new_tab method with auto_increment
+def create_multiple_tabs():
+    # Creates "Untitled_0", "Untitled_1", "Untitled_2"
+    tabs.on_new_tab("Untitled", content, auto_increment=True)
+    tabs.on_new_tab("Untitled", content, auto_increment=True)
+    tabs.on_new_tab("Untitled", content, auto_increment=True)
+```
+
+**How it works:**
+- The TabsManager maintains an internal counter (`_tab_count`)
+- When `auto_increment=True`, the counter value is appended to the label
+- Counter increments with each auto-incremented tab creation
+- Useful for "New Tab 1", "New Tab 2" patterns in editors or tools
+
+### Duplicate Detection
+
+The TabsManager automatically detects and reuses tabs with identical content to prevent duplicates:
+
+```python
+# Create a control instance
+network = VisNetwork(parent=tabs, nodes=data, edges=edges)
+
+# First call creates a new tab
+tab_id_1 = tabs.create_tab("Network", network)
+
+# Second call with same label and component returns existing tab_id
+tab_id_2 = tabs.create_tab("Network", network)
+
+# tab_id_1 == tab_id_2  (True - same tab!)
+```
+
+**Detection criteria:**
+A tab is considered a duplicate if all three match:
+- Same `label`
+- Same `component_type` (component class prefix)
+- Same `component_id` (component instance ID)
+
+**Note:** This only works with `BaseInstance` components (MyFastHtml controls). Plain FastHTML elements don't have IDs and will always create new tabs.
+
+### Dynamic Content Updates
+
+You can update tabs dynamically during the session:
+
+```python
+# Initial tab creation
+tab_id = tabs.create_tab("Data View", Div("Loading..."))
+
+# Later, update with actual data
+def load_data():
+    data_content = Div(H2("Data"), P("Loaded content"))
+    tabs.change_tab_content(tab_id, "Data View", data_content)
+    # Returns HTMX response to update the UI
+```
+
+**Use cases:**
+- Loading data asynchronously
+- Refreshing tab content based on user actions
+- Updating visualizations with new data
+- Switching between different views in the same tab
+
+### Tab Search Menu
+
+The built-in search menu helps users navigate when many tabs are open:
+
+```python
+# The search menu is automatically created and includes:
+# - A Search control for filtering tabs by label
+# - Live filtering as you type
+# - Click to activate a tab from search results
+```
+
+**How to access:**
+- Click the ⊞ icon in the tab header
+- Start typing to filter tabs by label
+- Click a result to activate that tab
+
+The search menu updates automatically when tabs are added or removed.
+
+### HTMX Out-of-Band Swaps
+
+For advanced HTMX control, you can customize swap behavior:
+
+```python
+# Standard behavior (out-of-band swap enabled)
+tabs.show_tab(tab_id, oob=True)  # Default
+
+# Custom target behavior (disable out-of-band)
+tabs.show_tab(tab_id, oob=False)  # Swap into HTMX target only
+```
+
+**When to use `oob=False`:**
+- When you want to control the exact HTMX target
+- When combining with other HTMX responses
+- When the tab activation is triggered by a command with a specific target
+
+**When to use `oob=True` (default):**
+- Most common use case
+- Allows other controls to trigger tab changes without caring about targets
+- Enables automatic UI updates across multiple elements
+
+### CSS Customization
+
+The TabsManager uses CSS classes that you can customize:
+
+| Class                      | Element                          |
+|----------------------------|----------------------------------|
+| `mf-tabs-manager`          | Root tabs manager container      |
+| `mf-tabs-header-wrapper`   | Header wrapper (buttons + menu)  |
+| `mf-tabs-header`           | Tab buttons container            |
+| `mf-tab-button`            | Individual tab button            |
+| `mf-tab-active`            | Active tab button (modifier)     |
+| `mf-tab-label`             | Tab label text                   |
+| `mf-tab-close-btn`         | Close button (×)                 |
+| `mf-tab-content-wrapper`   | Content area container           |
+| `mf-tab-content`           | Individual tab content           |
+| `mf-empty-content`         | Empty state when no tabs         |
+
+**Example customization:**
+
+```css
+/* Change active tab color */
+.mf-tab-active {
+    background-color: #3b82f6;
+    color: white;
+}
+
+/* Customize close button */
+.mf-tab-close-btn:hover {
+    color: red;
+}
+
+/* Style the content area */
+.mf-tab-content-wrapper {
+    padding: 2rem;
+    background-color: #f9fafb;
+}
+```
+
+## Examples
+
+### Example 1: Multi-view Application
+
+A typical application with different views accessible through tabs:
+
+```python
+from fasthtml.common import *
+from myfasthtml.controls.TabsManager import TabsManager
+from myfasthtml.core.instances import RootInstance
+
+# Create tabs manager
+root = RootInstance(session)
+tabs = TabsManager(parent=root, _id="app-tabs")
+
+# Dashboard view
+dashboard = Div(
+    H1("Dashboard"),
+    Div(
+        Div("Total Users: 1,234", cls="stat"),
+        Div("Active Sessions: 56", cls="stat"),
+        Div("Revenue: $12,345", cls="stat"),
+        cls="stats-grid"
+    )
+)
+
+# Analytics view
+analytics = Div(
+    H1("Analytics"),
+    P("Detailed analytics and reports"),
+    Div("Chart placeholder", cls="chart-container")
+)
+
+# Settings view
+settings = Div(
+    H1("Settings"),
+    Form(
+        Label("Username:", Input(name="username", value="admin")),
+        Label("Email:", Input(name="email", value="admin@example.com")),
+        Button("Save", type="submit"),
+    )
+)
+
+# Create tabs
+tabs.create_tab("Dashboard", dashboard)
+tabs.create_tab("Analytics", analytics)
+tabs.create_tab("Settings", settings)
+
+# Render
+return tabs
+```
+
+### Example 2: Dynamic Tabs with VisNetwork
+
+Creating tabs dynamically with interactive network visualizations:
+
+```python
+from fasthtml.common import *
+from myfasthtml.controls.TabsManager import TabsManager
+from myfasthtml.controls.VisNetwork import VisNetwork
+from myfasthtml.controls.helpers import mk
+from myfasthtml.core.commands import Command
+from myfasthtml.core.instances import RootInstance
+
+root = RootInstance(session)
+tabs = TabsManager(parent=root, _id="network-tabs")
+
+# Create initial tab with welcome message
+tabs.create_tab("Welcome", Div(
+    H1("Network Visualizer"),
+    P("Click 'Add Network' to create a new network visualization")
+))
+
+# Function to create a new network tab
+def add_network_tab():
+    # Define network data
+    nodes = [
+        {"id": 1, "label": "Node 1"},
+        {"id": 2, "label": "Node 2"},
+        {"id": 3, "label": "Node 3"}
+    ]
+    edges = [
+        {"from": 1, "to": 2},
+        {"from": 2, "to": 3}
+    ]
+
+    # Create network instance
+    network = VisNetwork(parent=tabs, nodes=nodes, edges=edges)
+
+    # Use auto-increment to create unique labels
+    return tabs.on_new_tab("Network", network, auto_increment=True)
+
+# Create command for adding networks
+add_cmd = Command("add_network", "Add network tab", add_network_tab)
+
+# Add button to create new network tabs
+add_button = mk.button("Add Network", command=add_cmd, cls="btn btn-primary")
+
+# Return tabs and button
+return Div(add_button, tabs)
+```
+
+### Example 3: Tab Management with Content Updates
+
+An application that updates tab content based on user interaction:
+
+```python
+from fasthtml.common import *
+from myfasthtml.controls.TabsManager import TabsManager
+from myfasthtml.controls.helpers import mk
+from myfasthtml.core.commands import Command
+from myfasthtml.core.instances import RootInstance
+
+root = RootInstance(session)
+tabs = TabsManager(parent=root, _id="editor-tabs")
+
+# Create initial document tabs
+doc1_id = tabs.create_tab("Document 1", Textarea("Initial content 1", rows=10))
+doc2_id = tabs.create_tab("Document 2", Textarea("Initial content 2", rows=10))
+
+# Function to refresh a document's content
+def refresh_document(tab_id, doc_name):
+    # Simulate loading new content
+    new_content = Textarea(f"Refreshed content for {doc_name}\nTimestamp: {datetime.now()}", rows=10)
+    tabs.change_tab_content(tab_id, doc_name, new_content)
+    return tabs._mk_tabs_controller(oob=True), tabs._mk_tabs_header_wrapper(oob=True)
+
+# Create refresh commands
+refresh_doc1 = Command("refresh_1", "Refresh doc 1", refresh_document, doc1_id, "Document 1")
+refresh_doc2 = Command("refresh_2", "Refresh doc 2", refresh_document, doc2_id, "Document 2")
+
+# Add refresh buttons
+controls = Div(
+    mk.button("Refresh Document 1", command=refresh_doc1, cls="btn btn-sm"),
+    mk.button("Refresh Document 2", command=refresh_doc2, cls="btn btn-sm"),
+    cls="controls-bar"
+)
+
+return Div(controls, tabs)
+```
+
+### Example 4: Using Auto-increment for Dynamic Tabs
+
+Creating multiple tabs programmatically with auto-generated labels:
+
+```python
+from fasthtml.common import *
+from myfasthtml.controls.TabsManager import TabsManager
+from myfasthtml.controls.helpers import mk
+from myfasthtml.core.commands import Command
+from myfasthtml.core.instances import RootInstance
+
+root = RootInstance(session)
+tabs = TabsManager(parent=root, _id="dynamic-tabs")
+
+# Create initial placeholder tab
+tabs.create_tab("Start", Div(
+    H2("Welcome"),
+    P("Click 'New Tab' to create numbered tabs")
+))
+
+# Function to create a new numbered tab
+def create_numbered_tab():
+    content = Div(
+        H2("New Tab Content"),
+        P(f"This tab was created dynamically"),
+        Input(placeholder="Enter some text...", cls="input")
+    )
+    # Auto-increment creates "Tab_0", "Tab_1", "Tab_2", etc.
+    return tabs.on_new_tab("Tab", content, auto_increment=True)
+
+# Create command
+new_tab_cmd = Command("new_tab", "Create new tab", create_numbered_tab)
+
+# Add button
+new_tab_button = mk.button("New Tab", command=new_tab_cmd, cls="btn btn-primary")
+
+return Div(
+    Div(new_tab_button, cls="toolbar"),
+    tabs
+)
+```
+
+---
+
+## Developer Reference
+
+This section contains technical details for developers working on the TabsManager component itself.
+
+### State
+
+The TabsManager component maintains the following state properties:
+
+| Name                       | Type            | Description                                          | Default |
+|----------------------------|-----------------|------------------------------------------------------|---------|
+| `tabs`                     | dict[str, Any]  | Dictionary of tab metadata (id, label, component)    | `{}`    |
+| `tabs_order`               | list[str]       | Ordered list of tab IDs                              | `[]`    |
+| `active_tab`               | str \| None     | ID of the currently active tab                       | `None`  |
+| `ns_tabs_content`          | dict[str, Any]  | Cache of tab content (raw, not wrapped)              | `{}`    |
+| `ns_tabs_sent_to_client`   | set             | Set of tab IDs already sent to client                | `set()` |
+
+**Note:** Properties prefixed with `ns_` are not persisted in the database and exist only for the session.
+
+### Commands
+
+Available commands for programmatic control:
+
+| Name                                    | Description                                    |
+|-----------------------------------------|------------------------------------------------|
+| `show_tab(tab_id)`                      | Activate or show a specific tab                |
+| `close_tab(tab_id)`                     | Close a specific tab                           |
+| `add_tab(label, component, auto_increment)` | Add a new tab with optional auto-increment |
+
+### Public Methods
+
+| Method                                                  | Description                                          |
+|---------------------------------------------------------|------------------------------------------------------|
+| `create_tab(label, component, activate=True)`           | Create a new tab or reuse existing duplicate         |
+| `show_tab(tab_id, activate=True, oob=True)`             | Send tab to client and/or activate it                |
+| `close_tab(tab_id)`                                     | Close and remove a tab                               |
+| `change_tab_content(tab_id, label, component, activate=True)` | Update existing tab's label and content      |
+| `on_new_tab(label, component, auto_increment=False)`    | Create and show tab with auto-increment support      |
+| `add_tab_btn()`                                         | Returns add tab button element                       |
+| `get_state()`                                           | Returns the TabsManagerState object                  |
+| `render()`                                              | Renders the complete TabsManager component           |
+
+### High Level Hierarchical Structure
+
+```
+Div(id="{id}", cls="mf-tabs-manager")
+├── Div(id="{id}-controller")                 # Controller (hidden, manages active state)
+├── Div(id="{id}-header-wrapper")             # Header wrapper
+│   ├── Div(id="{id}-header")                 # Tab buttons container
+│   │   ├── Div (mf-tab-button)               # Tab button 1
+│   │   │   ├── Span (mf-tab-label)           # Label (clickable)
+│   │   │   └── Span (mf-tab-close-btn)       # Close button
+│   │   ├── Div (mf-tab-button)               # Tab button 2
+│   │   └── ...
+│   └── Div (dropdown)                        # Search menu
+│       ├── Icon (tabs24_regular)             # Menu toggle button
+│       └── Div (dropdown-content)            # Search component
+├── Div(id="{id}-content-wrapper")            # Content wrapper
+│   ├── Div(id="{id}-{tab_id_1}-content")     # Tab 1 content
+│   ├── Div(id="{id}-{tab_id_2}-content")     # Tab 2 content
+│   └── ...
+└── Script                                     # Initialization script
+```
+
+### Element IDs
+
+| Name                          | Description                              |
+|-------------------------------|------------------------------------------|
+| `{id}`                        | Root tabs manager container              |
+| `{id}-controller`             | Hidden controller managing active state  |
+| `{id}-header-wrapper`         | Header wrapper (buttons + search)        |
+| `{id}-header`                 | Tab buttons container                    |
+| `{id}-content-wrapper`        | Content area wrapper                     |
+| `{id}-{tab_id}-content`       | Individual tab content                   |
+| `{id}-search`                 | Search component ID                      |
+
+**Note:** `{id}` is the TabsManager instance ID, `{tab_id}` is the UUID of each tab.
+
+### Internal Methods
+
+These methods are used internally for rendering:
+
+| Method                                  | Description                                           |
+|-----------------------------------------|-------------------------------------------------------|
+| `_mk_tabs_controller(oob=False)`        | Renders the hidden controller element                 |
+| `_mk_tabs_header_wrapper(oob=False)`    | Renders the header wrapper with buttons and search    |
+| `_mk_tab_button(tab_data)`              | Renders a single tab button                           |
+| `_mk_tab_content_wrapper()`             | Renders the content wrapper with active tab content   |
+| `_mk_tab_content(tab_id, content)`      | Renders individual tab content div                    |
+| `_mk_show_tabs_menu()`                  | Renders the search dropdown menu                      |
+| `_wrap_tab_content(tab_content)`        | Wraps tab content for HTMX out-of-band insertion      |
+| `_get_or_create_tab_content(tab_id)`    | Gets tab content from cache or creates it             |
+| `_dynamic_get_content(tab_id)`          | Retrieves component from InstancesManager             |
+| `_tab_already_exists(label, component)` | Checks if duplicate tab exists                        |
+| `_add_or_update_tab(...)`               | Internal method to add/update tab in state            |
+| `_get_ordered_tabs()`                   | Returns tabs ordered by tabs_order list               |
+| `_get_tab_list()`                       | Returns list of tab dictionaries in order             |
+| `_get_tab_count()`                      | Returns and increments internal tab counter           |
+
+### Tab Metadata Structure
+
+Each tab in the `tabs` dictionary has the following structure:
+
+```python
+{
+    'id': 'uuid-string',              # Unique tab identifier
+    'label': 'Tab Label',             # Display label
+    'component_type': 'prefix',       # Component class prefix (or None)
+    'component_id': 'instance-id'     # Component instance ID (or None)
+}
+```
+
+**Note:** `component_type` and `component_id` are `None` for plain FastHTML elements that don't inherit from `BaseInstance`.