phg/pve-vm-setup
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Enhance documentation for UI consistency and field widget layout in README, SPEC, and TASKS

Browse source
This commit is contained in:
Philip Henning 2026-03-08 11:52:24 +01:00
parent a34229a6ae
commit 34a0627e76
3 changed files with 18 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -11,7 +11,7 @@
- Write tests before implementation - Write tests before implementation
- Prefer small PR-sized tasks - Prefer small PR-sized tasks
- Keep business logic out of widgets where possible - Keep business logic out of widgets where possible
- Field-like widgets should default to compact 3-row controls with no empty spacer line between the value row and the border
- Every screen must have empty/loading/error coverage - Every screen must have empty/loading/error coverage
- Every interactive feature needs at least one Pilot test - Every interactive feature needs at least one Pilot test
- Visual changes should be covered by snapshot tests - Visual changes should be covered by snapshot tests

10
SPEC.md
View file

@ -21,6 +21,14 @@ Default: The PAM realm will be selected by default, but users can choose other r
Users will be able to create VMs by selecting from predefined templates. The script will handle the necessary API calls to create and configure the VM based on user input. Users will be able to create VMs by selecting from predefined templates. The script will handle the necessary API calls to create and configure the VM based on user input.
#### UI consistency
Field-like widgets should follow the compact Textual widget-gallery pattern used for single-line controls.
- Most field-like widgets should be 3 rows high by default.
- There must be no blank spacer line between the field content area and the surrounding border.
- Taller controls are only acceptable when a widget is intentionally multi-line or requires additional vertical content.
#### General #### General
This screen will show the general configuration options for the VM, such as: This screen will show the general configuration options for the VM, such as:
@ -202,7 +210,9 @@ The script will include error handling to manage API errors, authentication fail
The script will be tested using Textual interaction tests with run_test() and Pilot. Business logic will be kept in a central module, and testing will include running pytest, ruff check .., and ruff format .. . The script will be tested using Textual interaction tests with run_test() and Pilot. Business logic will be kept in a central module, and testing will include running pytest, ruff check .., and ruff format .. .
Add snapshot coverage for default, loading, and error states. Add snapshot coverage for default, loading, and error states.
For form-heavy screens, use snapshot coverage and visual review to confirm that single-line field widgets render as compact 3-row controls and do not show an empty spacer line inside the border.
### Documentation ### Documentation
The script will be well-documented, summarizing changes and any unresolved UX concerns. The script will be well-documented, summarizing changes and any unresolved UX concerns.
Document any intentional deviation from the compact 3-row field-widget layout or the no-inner-spacer rule as an explicit UX choice.

7
TASKS.md
View file

@ -11,6 +11,7 @@ Use these rules for every implementation task in this repository:
- Use `ruff` for linting and formatting. - Use `ruff` for linting and formatting.
- Prefer small vertical slices that can be implemented and verified independently. - Prefer small vertical slices that can be implemented and verified independently.
- Keep Proxmox API and business logic out of Textual widgets where possible. - Keep Proxmox API and business logic out of Textual widgets where possible.
- Field-like widgets should use compact 3-row layouts by default; bordered fields must not include an empty inner spacer row between the content and the border.
- Every screen must have explicit default, loading, success, empty, and error states where applicable. - Every screen must have explicit default, loading, success, empty, and error states where applicable.
- Every interactive screen must be covered by Textual interaction tests using `run_test()` and `Pilot`. - Every interactive screen must be covered by Textual interaction tests using `run_test()` and `Pilot`.
- Important visual states should be covered by snapshot tests. - Important visual states should be covered by snapshot tests.
@ -26,6 +27,12 @@ Codex should use these commands:
- Run lint checks: `uv run ruff check .` - Run lint checks: `uv run ruff check .`
- Format code: `uv run ruff format .` - Format code: `uv run ruff format .`
## Shared visual validation
- Use snapshot tests and visual review for form-heavy screens to confirm that single-line field widgets stay 3 rows high by default.
- Verify that bordered field-like controls do not render an empty spacer line above or below the value row.
- Allow taller controls only when a widget is intentionally multi-line or needs additional vertical content, and call that out in the task summary as a UX choice.
## Implementation backlog ## Implementation backlog
### Task 1: Bootstrap the Textual app and project structure ### Task 1: Bootstrap the Textual app and project structure