Docs: Add in-depth guide to ASCII UI Layout Map DSL
This commit is contained in:
@@ -40,6 +40,7 @@ This documentation suite provides comprehensive technical reference for the Manu
|
||||
| [Discussions](guide_discussions.md) | The Discussion system: 23-operation matrix A1-A7 (per-entry) + B1-B11 (discussion-level) + C1-C5 (undo/redo), Take naming convention (`<base>_take_<n>`), branching at any entry (`project_manager.branch_discussion`), promotion to top-level (`project_manager.promote_take`), user-managed role list (`app.disc_roles`), per-role filter linked to MMA persona focus, `_disc_entries_lock` thread-safety contract, Hook API session endpoints |
|
||||
| [State Lifecycle](guide_state_lifecycle.md) | Undo/redo via `HistoryManager` + `UISnapshot` (13 captured fields, 100-snapshot capacity, debounced change detection at render frame), reset flow (`_handle_reset_session` — clears 30+ fields, replaces project, preserves `active_project_path` per the 2026-06-08 regression fix), `App.__getattr__`/`__setattr__` state delegation to Controller, 8-thread io_pool with 11 lock-protected regions (per `IO_POOL_MAX_WORKERS = 8` in `src/io_pool.py:20`; bumped 4→8 in 4a338486 on 2026-06-06), hot-reload integration |
|
||||
| [Context Aggregation](guide_context_aggregation.md) | The `aggregate.py` (518-line) pipeline: 3 aggregation strategies (`auto`/`summarize`/`full`), 7 per-file view modes (`full`/`summary`/`skeleton`/`outline`/`masked`/`custom`/`none`), full `FileItem` schema (9 fields + `__post_init__` normalizer), `ContextPreset` schema and `ContextPresetManager`, Tier 3 worker variant (`build_tier3_context` with FuzzyAnchor re-resolution and focus-file handling), `force_full`/`auto_aggregate` short-circuits, output file numbering, cache strategy (static prefix + dynamic history) |
|
||||
| [ASCII Layout Map](guide_ascii_layout_map.md) | Structured text DSL reference: core conventions and vocabulary (lexicon of widgets, borders, separators), high-resolution zooming micro-sketches, grid-based alignment overlay, state multiplicity conditional annotations, and SSDL operational flow mappings. |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,185 @@
|
||||
# Guide to ASCII UI Layout Maps (DSL)
|
||||
|
||||
This guide defines the syntax, visual vocabulary, and operational conventions of the **ASCII UI Layout Map DSL** used in the Manual Slop codebase. This DSL serves as a text-side design contract between the specification phase and the immediate-mode ImGui rendering implementation in `src/gui_2.py` and other UI components.
|
||||
|
||||
---
|
||||
|
||||
## 1. Rationale: Why ASCII for ImGui?
|
||||
|
||||
Immediate-mode graphical user interfaces (IMGUIs) like dear imgui have three properties that make them highly compatible with structured ASCII text representations:
|
||||
|
||||
1. **Rectilinear Layouts:** IMGUI widgets are strictly rectangular, aligned horizontally or vertically, and positioned deterministically.
|
||||
2. **Regular Grammar:** Widget patterns (collapsible trees, sliders, combos, and tables) follow standard, recurring visual cues.
|
||||
3. **Information-Dense, Not Ornate:** Layout Maps focus on *what information is presented and how it is structured*, rather than pixel-perfect colors, paddings, or border-radius values.
|
||||
|
||||
Using ASCII Layout Maps allows developer-agents and users to share, iterate, and lock down user interface specifications directly within the text medium before committing to complex GUI implementation.
|
||||
|
||||
---
|
||||
|
||||
## 2. Core Conventions & Vocabulary
|
||||
|
||||
The ASCII UI Layout Map DSL uses a fixed set of symbols to represent standard ImGui controls.
|
||||
|
||||
### Widget Lexicon
|
||||
|
||||
| Widget Class | ASCII Symbol | Example | Specification |
|
||||
|---|---|---|---|
|
||||
| **Window Container** | `=...=` | `+=== My Window ===+` | Represents a top-level OS or ImGui window wrapper. |
|
||||
| **Child Panel / Pane** | `+---+` | `+----------------+` | Represents a scrollable or bounded child section (`imgui.begin_child`). |
|
||||
| **Button** | `[Label]` | `[Save]` | Bounded by square brackets; no internal padding by default. |
|
||||
| **Checkbox (Unchecked)**| `[ ]` | `[ ] Word-wrap` | Interactive checkbox in the off/inactive state. |
|
||||
| **Checkbox (Checked)** | `[X]` or `[✓]` | `[X] Auto-Scroll` | Interactive checkbox in the on/active state. |
|
||||
| **Radio Button (Off)** | `( )` | `( ) Global` | Mutually exclusive option in the inactive state. |
|
||||
| **Radio Button (On)** | `(o)` or `(•)` | `(o) Project` | Mutually exclusive option in the active state. |
|
||||
| **Dropdown / Combo** | `[Value v]` | `[gemini v]` | The lowercase `v` indicates a dropdown picker. |
|
||||
| **Dropdown (Selected)**| `[Label: Value v]` | `[Role: AI v]` | Displays both the field name and its active selection. |
|
||||
| **Text Input (Single)**| `|Value|` | `|C:\projects\slop|`| Bounded by pipes (`\|`), representing a text input field. |
|
||||
| **Slider / Drag Int** | `[===-----]` | `[=====---] 62%` | Represents a slider or drag-float/int showing current progress. |
|
||||
| **Tree Node (Closed)** | `> Label` | `> file_io` | A collapsible header or directory node in the collapsed state. |
|
||||
| **Tree Node (Open)** | `v Label` | `v file_io` | A collapsible header or directory node in the expanded state. |
|
||||
| **Table / Columns** | `\|` | `\| Name \| Size \|` | Columns separated by single pipes, indicating a tabular layout. |
|
||||
| **Separator** | `---` | `---` | A horizontal rule (`imgui.separator`). |
|
||||
| **Truncation Marker** | `...` | `...rest of 8KB...` | Indicates content or elements cropped out for layout brevity. |
|
||||
|
||||
---
|
||||
|
||||
## 3. High-Resolution Challenges & Advanced Techniques
|
||||
|
||||
When a panel is highly complex, dense, or dynamically nested, a single, low-resolution ASCII map may fail to convey the necessary layout details. In these scenarios, the DSL utilizes three advanced layout techniques: **Feature Zooming**, **Grid-Based Focus**, and **State Multiplicity Annotation**.
|
||||
|
||||
### 3.1 Feature Zooming
|
||||
|
||||
Feature Zooming decomposes a complex interface into a parent macro-layout and multiple zoomed micro-layouts. The macro-layout uses a descriptive placeholder badge `[Zoom: Component Name]` to signal that a detailed sub-layout exists below.
|
||||
|
||||
#### Macro-Layout (High-Level Grid)
|
||||
```
|
||||
+========================= Workspace Hub =========================+
|
||||
| Tabs: [Discussion] [Files] [Settings] |
|
||||
+-----------------------------------------------------------------+
|
||||
| |
|
||||
| [Zoom: Files Sidebar] | [Zoom: Details Editor] |
|
||||
| | |
|
||||
+=================================================================+
|
||||
```
|
||||
|
||||
#### Micro-Layout: Zoom 1 (Files Sidebar)
|
||||
```
|
||||
[Zoom: Files Sidebar]
|
||||
+--------------------------+
|
||||
| Filter: |*.py| |
|
||||
| v src |
|
||||
| [x] gui_2.py (8KB) |
|
||||
| [ ] ai_client.py (4KB) |
|
||||
| > tests |
|
||||
+--------------------------+
|
||||
```
|
||||
|
||||
#### Micro-Layout: Zoom 2 (Details Editor)
|
||||
```
|
||||
[Zoom: Details Editor]
|
||||
+-------------------------------------------------------------+
|
||||
| Active: gui_2.py |
|
||||
| File Mode: [masked v] [Force Full] [x] Auto-Aggregate |
|
||||
| --- |
|
||||
| Fuzzy Anchor Slices: |
|
||||
| [New Slice] |
|
||||
| | #L12-30: class App | |
|
||||
+-------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Grid-Based Focus Layouts
|
||||
|
||||
Grid-Based Focus overlays a logical coordinate system (columns `A, B, C...` and rows `1, 2, 3...`) onto the layout map. This is particularly useful for specifying precise immediate-mode alignment (`imgui.same_line()`) and relative widths under high layout density.
|
||||
|
||||
```
|
||||
Grid Focus Map:
|
||||
A B C
|
||||
+-----------------------+----------------------+--------------------+
|
||||
1 | Preset: [default v] | [Save Preset] | [Delete] |
|
||||
+-----------------------+----------------------+--------------------+
|
||||
2 | Temp: [=============] | [ ] Show Advanced |
|
||||
+-----------------------+-------------------------------------------+
|
||||
```
|
||||
|
||||
#### Alignment & Layout Matrix
|
||||
|
||||
* **Row 1:**
|
||||
* `A1`: Width 40% of viewport. Combo box selecting layout presets.
|
||||
* `B1`: `same_line()` called with 10px spacing. Fixed-width button.
|
||||
* `C1`: `same_line()` called, right-aligned to content region edge. Fixed-width warning-tinted button.
|
||||
* **Row 2:**
|
||||
* `A2`: Width 60% of viewport. Float slider for temperature.
|
||||
* `B2`: `same_line()` called. Toggle checkbox spanning the remaining region.
|
||||
|
||||
---
|
||||
|
||||
### 3.3 State Multiplicity Annotation
|
||||
|
||||
Immediate-mode UI layouts change shape based on state variables (e.g. read mode vs. edit mode). A Layout Map can document these variations by appending a `[State: Variable == Value]` condition block above or inline with the layout.
|
||||
|
||||
#### Read Mode Layout
|
||||
```
|
||||
[State: app.discussion_mode == "read"]
|
||||
+-----------------------------------------------------------------+
|
||||
| [Role: User] @ 12:34:56 [Edit] |
|
||||
| |
|
||||
| "How does the RAG aggregation logic handle file summaries?" |
|
||||
+-----------------------------------------------------------------+
|
||||
```
|
||||
|
||||
#### Edit Mode Layout
|
||||
```
|
||||
[State: app.discussion_mode == "edit"]
|
||||
+-----------------------------------------------------------------+
|
||||
| [Role: User v] @ 12:34:56 [Read] |
|
||||
| |
|
||||
| +-------------------------------------------------------------+ |
|
||||
| | How does the RAG aggregation logic handle file summaries? | |
|
||||
| +-------------------------------------------------------------+ |
|
||||
| [Save Changes] [Discard] |
|
||||
+-----------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Integration with SSDL (DAG Context)
|
||||
|
||||
ASCII Layout Maps must correspond to the **SSDL (Spec/Sketch Description Language)** operational flow defined in the function's docstring. SSDL maps the control flow and data mutation path through the immediate-mode graph.
|
||||
|
||||
### Mapping SSDL Primitives to Layout Widgets
|
||||
|
||||
* `[I:widget_name]` (Instruction) maps to a static widget, label, or display field.
|
||||
* `[B:widget_name]` (Branch) maps to interactive elements (e.g., checkboxes, dropdowns, popups) that fork control flow or toggle visibility of subsequent blocks.
|
||||
* `[S:widget_name]` (Stateful Mutation) maps to input fields, sliders, or action buttons that alter values on the `App` or `Controller` state.
|
||||
* `=>` (Wide path) maps to multi-column layouts, tables, or tabs where rendering branches concurrently.
|
||||
|
||||
#### Example Alignment
|
||||
|
||||
```python
|
||||
def render_example_panel(app: App) -> None:
|
||||
"""Renders a simple model parameter panel.
|
||||
|
||||
SSDL: `[I:header] -> [B:enable_override] -> [S:temp_slider] => [B:status_badge]`
|
||||
|
||||
ASCII Layout Map:
|
||||
+---------------------------------------------------------+
|
||||
| Model Parameters | <- [I:header]
|
||||
| [X] Override Default Parameters | <- [B:enable_override]
|
||||
| Temperature: [=======---------] 0.70 | <- [S:temp_slider] (indented if enabled)
|
||||
| --- |
|
||||
| Status: READY | <- [B:status_badge] (green if ready)
|
||||
+---------------------------------------------------------+
|
||||
"""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Development & Verification Loop
|
||||
|
||||
When modifying or implementing layout panels, developers must follow a strict verification sequence to ensure that layout maps align with source code without introducing runtime bugs:
|
||||
|
||||
1. **AST Check:** Run `py_check_syntax` on the modified file immediately after editing the docstrings.
|
||||
2. **Regression Check:** Run `pytest tests/` to confirm that docstring formatting changes have not caused runtime syntax or encoding errors.
|
||||
3. **Fidelity Comparison:** Under the `Puppeteer` testing pattern, run visual simulations to capture actual ImGui viewport coordinates and ensure they correspond to the rows, columns, and zoom structures mapped in the ASCII DSL contract.
|
||||
Reference in New Issue
Block a user