summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorWarry <FunWarry@users.noreply.github.com>2025-11-30 15:37:32 +0100
committerWarry <FunWarry@users.noreply.github.com>2025-11-30 15:37:32 +0100
commit121dbb788d051c76375261cd18fa8dca0f23b935 (patch)
treecab3f2df3aa9e1437fdd0b5c60ab22780f8d717d /docs
parent28a6fe5a7dbadc9532de228a539c47ec49ca4aa2 (diff)
downloadtidal-dl-ng-121dbb788d051c76375261cd18fa8dca0f23b935.tar.gz
feat: refactor settings UI with category navigation and add Delimiters page
Closes #640 ## Changes ### UI Refactoring - Replace monolithic settings dialog with category-based navigation - Add QListWidget (lw_categories) for category selection on the left - Add QStackedWidget (sw_categories) for content pages on the right - Organize settings into 5 distinct pages: - Flags (14 checkboxes) - Quality (3 combo boxes) - Numbers (2 spin boxes) - Paths & Formats (7 line edits + 2 browse buttons) - Delimiters (4 line edits) — NEW ### New Feature: Delimiters Category - Add customizable separators for artists in metadata and filenames: - metadata_delimiter_artist - metadata_delimiter_album_artist - filename_delimiter_artist - filename_delimiter_album_artist - Auto-integration with DialogPreferences via parameters_line_edit - Line edits with max width 100px for compact display ### Styling - Apply dark theme to settings dialog: - Category list: #2b2b2b background, #3d5a80 selection, #3a3a3a hover - Settings area: #333333 background, styled GroupBoxes (#3a3a3a) - Light text (#e0e0e0) for better contrast - Add spacing property (6px) to category list for better readability - Style QListWidget items with padding (4px 3px) and margin (2px 0px) ### Testing - Add comprehensive test suite (61 tests total): - test_settings_ui.py: UI and basic integration (14 tests) - test_settings_dialog_structure.py: detailed structure validation (20 tests) - test_dialog_preferences_integration.py: DialogPreferences integration (14 tests) - test_delimiters_category.py: new Delimiters page validation (13 tests) - Fix ruff issues (F841, S108) in test files - All tests passing with 100% success rate ### Documentation - Add docs/refactor_settings_ui.md: comprehensive refactor overview - Add docs/delimiters_category.md: Delimiters feature documentation - Add docs/ui_styles.md: dark theme style guide - Add docs/testing_summary.md: testing overview and commands ### Code Quality - Apply ruff/black/pyupgrade via pre-commit hooks - Fix F841 (unused variable) in test_dialog_preferences_integration.py - Fix S108 (insecure temp path) using Path.home() in test_settings_ui.py - End-of-file fixes applied automatically ## Files Modified - tidal_dl_ng/ui/dialog_settings.ui (complete restructure) - tidal_dl_ng/ui/dialog_settings.py (auto-generated from .ui) - tidal_dl_ng/dialog.py (add 4 delimiter params + Delimiters category) - tests/* (4 new test files with 61 tests) - docs/* (4 new documentation files) ## Impact - Improved UX: intuitive category navigation, better visual organization - Extensibility: easy to add new settings pages/categories - Quality: comprehensive test coverage ensures robustness - User flexibility: customizable separators for metadata and filenames ## Technical Notes - QStackedWidget pages indexed 0-4 matching category list order - Navigation via QListWidget::currentRowChanged signal - Automatic save/load through existing DialogPreferences methods - No breaking changes to existing settings or configuration ## Testing Commands ```powershell poetry run pre-commit run -a poetry run pytest -q
Diffstat (limited to 'docs')
-rw-r--r--docs/delimiters_category.md43
-rw-r--r--docs/refactor_settings_ui.md128
-rw-r--r--docs/testing_summary.md32
-rw-r--r--docs/ui_styles.md23
4 files changed, 226 insertions, 0 deletions
diff --git a/docs/delimiters_category.md b/docs/delimiters_category.md
new file mode 100644
index 0000000..0ef148b
--- /dev/null
+++ b/docs/delimiters_category.md
@@ -0,0 +1,43 @@
+# "Delimiters" Category
+
+## Goal
+
+Allow users to customize separators used for artists and album artists, both in metadata and filenames.
+
+## Parameters
+
+- `metadata_delimiter_artist`: artists separator (metadata)
+- `metadata_delimiter_album_artist`: album artists separator (metadata)
+- `filename_delimiter_artist`: artists separator (filename)
+- `filename_delimiter_album_artist`: album artists separator (filename)
+
+## UI
+
+- Page `page_delimiters` inside `sw_categories`
+- GroupBox `gb_delimiters`
+- 4 `QLineEdit` entries (`le_*`) with max width 100px
+
+## Integration
+
+- Add the 4 fields to `DialogPreferences.parameters_line_edit`
+- Load values via `populate_line_edit()`
+- Save via `to_settings()`
+
+## Tests
+
+- `tests/test_delimiters_category.py`: 13 tests
+ - Page existence
+ - Widgets accessibility
+ - Navigation to the page
+ - Width constraints
+
+## Examples
+
+- Semicolon: `"; "` → `Artist1; Artist2`
+- Ampersand: `" & "` → `Artist1 & Artist2`
+- Slash: `" / "` → `Artist1 / Artist2`
+
+## Notes
+
+- Default values are `", "` (comma + space)
+- Fields are kept short (max 100px) to avoid breaking the layout
diff --git a/docs/refactor_settings_ui.md b/docs/refactor_settings_ui.md
new file mode 100644
index 0000000..651427c
--- /dev/null
+++ b/docs/refactor_settings_ui.md
@@ -0,0 +1,128 @@
+# Settings Window Refactor
+
+Date: 2025-11-30
+Author: Automation (Copilot)
+
+## Goal
+
+Refactor the settings window to improve usability and maintainability:
+
+- Category list on the left
+- Settings content on the right via QStackedWidget
+- Clear separation of pages (Flags, Quality, Numbers, Paths & Formats, Delimiters)
+- Consistent dark styling and tuned spacing
+- Add unit and integration tests (61 total)
+
+## Key Changes
+
+### 1. UI Architecture
+
+- Navigation column: `QListWidget (lw_categories)`
+- Pages container: `QStackedWidget (sw_categories)`
+- Pages created:
+ - `page_flags` (GroupBox: gb_flags)
+ - `page_quality` (GroupBox: gb_choices)
+ - `page_numbers` (GroupBox: gb_numbers)
+ - `page_paths` (GroupBox: gb_path)
+ - `page_delimiters` (GroupBox: gb_delimiters) — NEW
+
+Impacted file: `tidal_dl_ng/ui/dialog_settings.ui` (auto-generated `dialog_settings.py`).
+
+### 2. New Category: Delimiters
+
+- "Delimiters" page with 4 `QLineEdit` fields to edit separators:
+ - `metadata_delimiter_artist`
+ - `metadata_delimiter_album_artist`
+ - `filename_delimiter_artist`
+ - `filename_delimiter_album_artist`
+- Automatic integration with `DialogPreferences` through `parameters_line_edit`, `populate_line_edit()` and `to_settings()`.
+
+Files touched:
+
+- `tidal_dl_ng/ui/dialog_settings.ui` (new page)
+- `tidal_dl_ng/ui/dialog_settings.py` (regenerated)
+- `tidal_dl_ng/dialog.py` (added 4 parameters and new category in `_init_categories`).
+
+### 3. Styles & Spacing
+
+- Category list: dark style, blue selection, gray hover, light text.
+- Vertical spacing: list item margin `2px 0px` (and optional view spacing).
+- Settings area: dark background (QStackedWidget), styled GroupBoxes.
+
+Files touched:
+
+- `tidal_dl_ng/ui/dialog_settings.ui` (stylesheets on lw_categories and sw_categories)
+- `tidal_dl_ng/ui/dialog_settings.py` (regenerated).
+
+### 4. Tests
+
+- New files:
+ - `tests/test_settings_ui.py`: UI and basic integration (14)
+ - `tests/test_settings_dialog_structure.py`: detailed structure (20)
+ - `tests/test_dialog_preferences_integration.py`: DialogPreferences integration (14)
+ - `tests/test_delimiters_category.py`: Delimiters page (13)
+- Total: **61 tests**; ruff/black/pyupgrade applied via pre-commit.
+
+### 5. Pre-commit & Quality
+
+- Ruff fixes:
+ - F841 (unused variable) in `test_dialog_preferences_integration.py`
+ - S108 (using /tmp) replaced by `Path.home()` and safe values
+- end-of-file-fixer and black reformatted automatically.
+
+## Usage
+
+### Launch the UI
+
+- Via the app: `poetry run tidal-dl-ng-gui` (or `python -m tidal_dl_ng.gui`)
+
+### Navigate
+
+- Select a category in `lw_categories`
+- The corresponding page shows in `sw_categories`.
+
+### Edit separators
+
+- Open the "Delimiters" category
+- Edit fields `le_metadata_delimiter_*` and `le_filename_delimiter_*`
+- Confirm via OK
+
+## Known issue: poetry+dulwich KeyError b'HEAD
+
+- Cause: dulwich cannot resolve HEAD in the Git repo when Poetry queries VCS info.
+- Fix: ensure `.git/HEAD` points to an existing branch (e.g. `ref: refs/heads/main`) and the branch exists; then re-run `poetry install`. See commands below.
+
+## Useful Commands (PowerShell)
+
+```powershell
+cd C:\Users\mathe\PycharmProjects\tidal-dl-ng
+poetry check --lock
+poetry run pre-commit run -a
+pytest -q
+```
+
+To fix HEAD if needed:
+
+```powershell
+cd C:\Users\mathe\PycharmProjects\tidal-dl-ng
+Get-Content .git\HEAD
+# If empty/incorrect:
+git init
+git add .
+git commit -m "Initialize repo for Poetry/Dulwich"
+git branch -M main
+Get-Content .git\HEAD
+poetry install -vvv --no-interaction --all-extras --with dev,docs
+```
+
+## Impact
+
+- Better UX: category navigation, improved readability
+- Extensible: easy to add new pages/settings
+- Quality: comprehensive tests ensure robustness
+
+## Next Steps
+
+- Add contextual help (tooltips) for new delimiter fields
+- Optionally adjust list spacing (8–10) based on feedback
+- Add a preview of resulting formatting (e.g., sample metadata)
diff --git a/docs/testing_summary.md b/docs/testing_summary.md
new file mode 100644
index 0000000..5229548
--- /dev/null
+++ b/docs/testing_summary.md
@@ -0,0 +1,32 @@
+# Created Tests and Results
+
+## Test files
+
+- `tests/test_settings_ui.py` (14 tests)
+- `tests/test_settings_dialog_structure.py` (20 tests)
+- `tests/test_dialog_preferences_integration.py` (14 tests)
+- `tests/test_delimiters_category.py` (13 tests)
+
+## Total
+
+- **61 tests** (unit + integration)
+
+## Coverage
+
+- UI creation and structure
+- Category navigation
+- Widgets presence and accessibility
+- New "Delimiters" page
+- Quality: ruff/black/pyupgrade enforced by pre-commit
+
+## Commands
+
+```powershell
+cd C:\Users\mathe\PycharmProjects\tidal-dl-ng
+poetry run pre-commit run -a
+pytest -q
+```
+
+## Note
+
+If `poetry install` fails with KeyError b'HEAD, see "Settings Window Refactor" doc to fix the Git repo’s HEAD.
diff --git a/docs/ui_styles.md b/docs/ui_styles.md
new file mode 100644
index 0000000..6e2a81e
--- /dev/null
+++ b/docs/ui_styles.md
@@ -0,0 +1,23 @@
+# UI Styles (Dark)
+
+## Category List (QListWidget)
+
+- Background: `#2b2b2b`
+- Selection: blue `#3d5a80` + white text
+- Hover: gray `#3a3a3a`
+- Text: light gray `#e0e0e0`
+- Padding: 4px
+- Item margin: 2px vertical
+- View spacing: 0 (can be set to 6–10 for more breathing room)
+
+## Settings Area (QStackedWidget)
+
+- Background: `#333333`
+- Border: `#3d3d3d`
+- GroupBox: background `#3a3a3a`, border `#4a4a4a`, radius 6
+
+## Tuning Tips
+
+- Increase view spacing to 8–10 if preferred visually
+- Harmonize corner radius with global UI style
+- Use tooltips to explain parameters