[3 / 7] - Mail Return

[TheSCREWEDSoftware]

Split from the main PR: #197

Split by Claude

Full overhaul: confirm prompt before returning, a 6×2 grid matching the 12-item mail cap, shows the recipient's faction/class, Wowhead tooltips + higher-res icons, and clean empty/loaded states.

Summary by CodeRabbit

Release Notes

• New Features

  • Added dark mode toggle for WordPress admin dashboard

• Improvements

  • Redesigned character ordering screen with visual enhancements and reset order option
  • Redesigned mail return interface with sidebar character navigation
  • Enhanced mail display with item quality information and improved metadata
  • Expanded admin styling and dark mode support across all admin pages

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces the AcoreCharColors PHP utility for WoW class/race/faction/expansion metadata. Uses it to redesign the Characters Order and Mail Return admin pages. Adds a nonce-protected reset-order action. Adds a persistent admin dark mode toggle backed by user meta and an AJAX handler. Ships dark-mode.css and theme.css alongside a substantially rewritten main.css.

Changes

Character Order & Mail Return UI Redesigns

Layer / File(s)	Summary
AcoreCharColors utility and boot wiring src/acore-wp-plugin/src/Utils/AcoreCharColors.php, src/acore-wp-plugin/src/boot.php	New static class with class/race/faction name maps, per-class light/dark hex colors, rowStyle() inline CSS output, and expansion slug/label helpers; loaded at boot.
Characters Order controller and view src/acore-wp-plugin/src/Components/CharactersMenu/CharactersController.php, src/acore-wp-plugin/src/Components/CharactersMenu/CharactersView.php	loadHome() adds nonce check and an acore_reset_order branch calling resetCharacterOrder() (new SQL UPDATE … SET order = NULL). View redesigned: per-character rows use AcoreCharColors for styling and level/race/class tooltips; Save and Reset buttons rendered in a flex container; sortable JS updated to renumber position labels on drag.
Mail Return controller SQL expansion src/acore-wp-plugin/src/Components/MailReturnMenu/MailReturnController.php	getSentUnreadMails SELECT expanded to include money and cod; item details query expanded to include it.Quality as item_quality.
Mail Return view redesign src/acore-wp-plugin/src/Components/MailReturnMenu/MailReturnView.php	Replaces inline mailReturnData JS with wp_localize_script; adds power.js; rewrites HTML from a <select> dropdown to a sidebar card-button character selector using AcoreCharColors metadata; restructures empty/loading/content containers.
Mail Return JS: card-click flow and quality rendering src/acore-wp-plugin/web/assets/mail-return/mail-return.js	Switches from select-change to card-click interaction; AJAX success path renders quality-colored item grids, CoD labels, expansion level badges, and runs upgradeWowheadIcons() (with polling fallback) to rewrite icon URLs to large JPGs.
main.css: character row, mail-return, and item-restore layouts src/acore-wp-plugin/web/assets/css/main.css	Replaces old #acore-characters-order/unstuck rules with a shared .acore-char-list/.acore-char-row flex system driven by CSS variables and expansion badges; replaces mail entry styling with a grid-based #mail-return-layout with WowHead overlay rules; adds profile #item-restore-layout sidebar grid and item card styles.

Admin Dark Mode Feature

Layer / File(s)	Summary
DarkMode PHP: hooks, AJAX handler, and inline JS src/acore-wp-plugin/src/Hooks/Various/DarkMode.php, src/acore-wp-plugin/src/boot.php	Registers admin bar toggle node, admin_body_class filter (appends acore-dark-mode), enqueues CSS layers plus inline toggle script on jquery-core, injects high-priority late <style> block, handles wp_ajax_acore_toggle_dark_mode (nonce check, flips acore_dark_mode user meta, returns JSON), and conditionally injects theme.css into the WP 2FA wizard page.
dark-mode.css: comprehensive page-level dark overrides src/acore-wp-plugin/web/assets/css/dark-mode.css	Covers profile/security/item-restore tables, expansion selector, Bootstrap 5 custom properties, WP core typography/postboxes/cards, character row states, mail entry colors, wp-list-table striping, buttons, notices, myCred widgets, Scroll of Resurrection page, expansion badges, and Mail Return page under body.acore-dark-mode.
theme.css: consolidated theme variables and cross-page overrides src/acore-wp-plugin/web/assets/css/theme.css	Defines :root and body.acore-dark-mode custom properties (including WoW quality colors); adds item-restore card quality borders, Security/Mail Return page surfaces, embedded WP 2FA dark styling, myCRED history/profile overrides, standalone WP 2FA wizard dark theming, connection-row highlighting, native form controls/buttons, WP 2FA modal, and additional myCRED admin tweaks.

Sequence Diagram(s)

sequenceDiagram
  participant Admin as Admin User
  participant Toggle as Admin Bar Toggle
  participant JS as Inline Toggle Script
  participant Ajax as wp_ajax_acore_toggle_dark_mode
  participant Meta as acore_dark_mode user meta

  Admin->>Toggle: Click dark mode toggle
  Toggle->>JS: Fire click handler
  JS->>Ajax: POST action + nonce
  Ajax->>Meta: Flip stored mode value
  Meta-->>Ajax: Return enabled state
  Ajax-->>JS: JSON success payload
  JS->>Toggle: Update icon and title
  JS->>Admin: Toggle body class acore-dark-mode

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐇 A bunny hops through admin land,
Dark moon or bright sun — you choose your brand!
Characters line up with colors and flair,
Reset their order? The button is there!
Mail returns glowing with quality hue,
The warren is cozy in dark mode too. 🌙

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.74% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title '[3 / 7] - Mail Return' directly refers to the main feature being developed in this PR, which is the redesigned Mail Return feature as documented in the objectives. The title is concise and clearly identifies the specific component being modified.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

src/acore-wp-plugin/web/assets/mail-return/mail-return.js (1)

36-63: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider providing constants via localized data.

The class colors (lines 36-40), race/class names (lines 50-57), and faction mappings (lines 60-62) duplicate the PHP constants in AcoreCharColors. If these values change in the PHP class, the JS must be manually updated.

Consider adding these to the mailReturnData object in MailReturnView.php via wp_localize_script() to maintain a single source of truth.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/acore-wp-plugin/web/assets/mail-return/mail-return.js` around lines 36 -
63, The classColors object, raceNames object, classNames object, and
allianceRaces array in mail-return.js are hardcoded duplicates of PHP constants
from AcoreCharColors. Move these data structures to the mailReturnData object in
MailReturnView.php and pass them to the JavaScript using wp_localize_script() so
they can be accessed from a single source of truth. Then update the references
in mail-return.js to use the localized mailReturnData object properties instead
of the hardcoded variable declarations.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/acore-wp-plugin/src/Components/CharactersMenu/CharactersController.php`:
- Around line 17-28: Fix the spelling error in the success message displayed
after saving character settings. In the else block following the
saveCharacterOrder() method call, locate the text "succesfully" in the message
"Character settings succesfully saved." and correct it to "successfully" to
match the standard English spelling.

In `@src/acore-wp-plugin/src/Components/MailReturnMenu/MailReturnView.php`:
- Around line 58-59: The src attributes for the race-icon and class-icon img
elements in MailReturnView.php need to be wrapped with the esc_url() function to
comply with WordPress coding standards. Locate both img tags (those with
class="race-icon" and class="class-icon") and wrap their entire src attribute
values with esc_url(), ensuring the concatenated URL string constructed from
ACORE_URL_PLG and the intval() conversions is properly escaped for use in URL
context.

In `@src/acore-wp-plugin/src/Hooks/Various/DarkMode.php`:
- Line 41: The wp_add_inline_script call attaching the dark mode toggle JS to
the 'jquery-core' handle can fail silently on admin screens where jquery-core is
not enqueued or printed, breaking the toggle functionality. Instead of targeting
jquery-core, register a new dedicated script handle (for example, a custom
handle like 'acore-dark-mode') using wp_register_script with jquery as a
dependency, then enqueue it and attach the inline script to this new guaranteed
handle using wp_add_inline_script. This ensures the toggle JS is always
available regardless of the screen context.

In `@src/acore-wp-plugin/src/Utils/AcoreCharColors.php`:
- Around line 84-94: The rowStyle method defines a variable `$fDark` that is
assigned but never used in the sprintf output. Remove the line that assigns
`$fDark` since only the `$fLight` variable is utilized in the returned style
string. This will eliminate the unused variable and clean up the code.

---

Nitpick comments:
In `@src/acore-wp-plugin/web/assets/mail-return/mail-return.js`:
- Around line 36-63: The classColors object, raceNames object, classNames
object, and allianceRaces array in mail-return.js are hardcoded duplicates of
PHP constants from AcoreCharColors. Move these data structures to the
mailReturnData object in MailReturnView.php and pass them to the JavaScript
using wp_localize_script() so they can be accessed from a single source of
truth. Then update the references in mail-return.js to use the localized
mailReturnData object properties instead of the hardcoded variable declarations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 79a1b2b5-82aa-43bd-aabe-eebeaeb6eff2

📥 Commits

Reviewing files that changed from the base of the PR and between 94af292 and 167a8cf.

📒 Files selected for processing (11)

• src/acore-wp-plugin/src/Components/CharactersMenu/CharactersController.php
• src/acore-wp-plugin/src/Components/CharactersMenu/CharactersView.php
• src/acore-wp-plugin/src/Components/MailReturnMenu/MailReturnController.php
• src/acore-wp-plugin/src/Components/MailReturnMenu/MailReturnView.php
• src/acore-wp-plugin/src/Hooks/Various/DarkMode.php
• src/acore-wp-plugin/src/Utils/AcoreCharColors.php
• src/acore-wp-plugin/src/boot.php
• src/acore-wp-plugin/web/assets/css/dark-mode.css
• src/acore-wp-plugin/web/assets/css/main.css
• src/acore-wp-plugin/web/assets/css/theme.css
• src/acore-wp-plugin/web/assets/mail-return/mail-return.js

[TheSCREWEDSoftware]

The reviews are valid for this, but the are fixed in the on the way to latest PR and including he last PR #205