retoor
29c489e27a
- In-tai.py TUI framework (panels, compositor, z-layers, mouse, focus, VT screen, pty sub-terminals, widgets, animation) plus /demo, --demo, --demo-shot, tui.md docs, and research/tui-framework-design archive - Focus safety: Tab/Shift+Tab always cycle, auto-focus prefers non-terminals, dialogs restore previous focus on close - Native Consts/Install/Sandbox/Opencode/SysInfo classes in tai.py; module functions delegate so live patches apply; fixes 19 failures - Retargeted 4 test patches to the real tai.* seams (assertions unchanged) - Deleted tai_pkg/; tai.py is standalone stdlib-only (bare copy imports) - AGENTS.md/README.md updated to the standalone architecture - test_tai.py 320/320 OK, test_seal.py 16/16 OK
56 lines
2.9 KiB
Markdown
56 lines
2.9 KiB
Markdown
# Layout - Textual (official guide)
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Institute | Molodetz Institute — Research & Retrieval Division |
|
|
| Subject | tui-framework-design |
|
|
| Document type | Source Dossier |
|
|
| Tier | 1 |
|
|
| Source title | Layout - Textual |
|
|
| Source URL | https://textual.textualize.io/guide/layout/ |
|
|
| Source publisher / author | Textualize |
|
|
| Source type | vendor docs |
|
|
| Source date (published) | Unknown — not stated |
|
|
| Date researched | 2026-10-10 |
|
|
| Researched by | tai (agent), model: Muse Spark, on behalf of retoor |
|
|
| Research method | direct page fetch |
|
|
| Confidence | High |
|
|
| Status | Active |
|
|
|
|
## Summary
|
|
|
|
Textual's official layout guide: containers arrange children with `vertical`, `horizontal`, or `grid` layouts; sizes use cells, `fr` fractions, `%`, or `auto`; `dock` pins widgets to an edge outside the flow; named `layers` control paint order; `offset` shifts widgets visually. Yield order decides paint order unless layers override it.
|
|
|
|
## Key findings
|
|
|
|
- Screen defaults to `vertical` layout; children stack top to bottom (vertical) or left to right (horizontal).
|
|
- `fr` units split free space proportionally (`height: 1fr` on three children = equal thirds); `%` sizes against the parent; `auto` sizes to content.
|
|
- Widgets expand to the parent's width by default but not its height (explicit `height: 100%` needed).
|
|
- `overflow-x/y: auto` adds scrollbars when children exceed the container; wheel/trackpad/keyboard scroll the focused container.
|
|
- `dock: top|right|bottom|left` removes a widget from flow and pins it to an edge; docked widgets never scroll (headers, footers, sidebars).
|
|
- Overlapping docked widgets paint in yield order: later yield = on top.
|
|
- `layers` on a container declares space-separated layer names (leftmost = lowest); descendants take `layer: <name>`; layer order beats yield order.
|
|
- Grid supports `grid-size`, `grid-columns`/`grid-rows` (incl. `auto`, `fr`, `%`), `row-span`/`column-span`, and `grid-gutter`.
|
|
|
|
## Pros / strengths
|
|
|
|
- Authoritative with a worked example per concept; the vocabulary (flow, dock, layers, offset) is small yet covers headers, sidebars, grids, and overlapping popups.
|
|
|
|
## Cons / limitations / caveats
|
|
|
|
- CSS-syntax specific; no algorithm internals (those live in Textual's `_compositor.py` source, not this guide).
|
|
- Utility containers (Vertical/Horizontal/Grid) are thin wrappers; the ideas matter more than the classes.
|
|
|
|
## Relevance to tai
|
|
|
|
- Supplies the exact layout vocabulary tai's Panel needs: rows/cols flow containers, `fr` + `%` + auto sizing, dock edges, named layers with z, offsets — matching the requested rows/cols/percentage/alignment feature set one for one.
|
|
- tai will express the same concepts as constructor kwargs and methods (no CSS parser): `Rows`, `Cols`, `dock="left"`, `layer="dialog"`, `offset=(x, y)`.
|
|
|
|
## Changelog
|
|
|
|
| Date | Change |
|
|
|---|---|
|
|
| 2026-10-10 | Initial dossier created. |
|