149 lines
8.5 KiB
Markdown
149 lines
8.5 KiB
Markdown
# Aurora Admin v2 — Project Status
|
|
|
|
_Last updated: 2026-07-03_
|
|
|
|
## What this project is
|
|
|
|
A ground-up rebuild of the "uiXpress" WordPress admin-theme plugin, relaunched
|
|
as **Aurora Admin**. The original plugin's look/feel and feature set are the
|
|
target, but **no original code is reused** — all Vue components, PHP classes,
|
|
Tailwind config, and build tooling are freshly written. This lives in
|
|
`aurora-admin-v2/` (the earlier in-place rebrand attempt, `aurora-admin-working/`,
|
|
is superseded and no longer the active codebase).
|
|
|
|
## Workflow rules established
|
|
|
|
- **Always verify live in Chrome** before declaring a fix done — the user was
|
|
burned by blind-iteration guesses costing time/money. Use the Chrome MCP
|
|
tools (`tabs_context_mcp`, `navigate`, `computer`/screenshot, `javascript_exec`)
|
|
to inspect real DOM/computed styles rather than guessing from source.
|
|
- **Zip packaging**: Windows `Compress-Archive` corrupts the WP upload (backslash
|
|
path separators break PHP's unzip). Always build the zip via PowerShell
|
|
`System.IO.Compression.ZipFile`, normalizing every entry path with
|
|
`.Replace('\', '/')`. Output goes to
|
|
`aurora-admin-v2-dist\aurora-admin\aurora-admin-v2.zip`.
|
|
- **Old build caching gotcha**: WordPress serves whatever plugin files were last
|
|
installed — if the user says "didn't fix it," suspect a stale zip still
|
|
installed before suspecting the code. Verify the live script hash via
|
|
`document.querySelector('script[src*="dashboard"]')` when in doubt.
|
|
- Site under test: `http://admin.local/wp-admin/`.
|
|
|
|
## Architecture
|
|
|
|
- **PHP** (`admin/src/...`, namespaced `AuroraAdmin\...`), bootstrapped from
|
|
`aurora-admin.php`, instantiated in `admin/src/App/AuroraAdmin.php`.
|
|
- **Vue 3** app (`app/src/...`), Vite multi-entry build → `manifest.json`,
|
|
read by `admin/src/Utility/Assets.php::enqueue()` which also walks the
|
|
manifest's `imports` chain to pull in shared-chunk CSS.
|
|
- **Single global stylesheet**: `app/src/shell/shell-frame.css` — defines all
|
|
`--aurora-*` CSS variables (incl. `.aurora-dark` overrides) and the only
|
|
rules that touch WP structural IDs (`#wpcontent`, `#wpbody-content`). No
|
|
element resets/utility classes leak onto native WP pages (this was the
|
|
root cause of the original rebrand's Tailwind-leakage bug — avoided here
|
|
by design).
|
|
- **Immersive shell** (`admin/src/Shell/Shell.php` + `app/src/shell/SiteShell.vue`
|
|
+ `Sidebar.vue` + `Toolbar.vue`): hides native WP chrome, mounts a Vue
|
|
sidebar/toolbar on every admin page. `MenuSerializer.php` converts WP's
|
|
`$menu`/`$submenu` globals into JSON for the sidebar.
|
|
- **Dashboard takeover** (`admin/src/Pages/DashboardTakeover.php` +
|
|
`app/src/pages/dashboard/Dashboard.vue`): hijacks native `index.php` via
|
|
`in_admin_header`, hides the native `.wrap`, renders the Aurora dashboard
|
|
in its place. 12-col grid; cards are single `<section class="aurora-card">`
|
|
elements with inline `grid-column: span N` (NOT wrapped — component
|
|
attribute fallthrough for styles was unreliable).
|
|
- **Settings page** (`admin/src/Pages/SettingsPage.php` + `app/src/pages/
|
|
settings/Settings.vue`): owns the top-level "Aurora Admin" admin menu
|
|
directly (no submenu). Two-box layout: `.settings__nav` (category list) +
|
|
`.settings__content` (fields), both boxed/bordered on a darker backdrop.
|
|
Field schema is declarative in `app/src/pages/settings/settingsConfig.js`,
|
|
rendered by `app/src/pages/settings/components/SettingsField.vue` (types:
|
|
text, toggle, color, image, repeater, multiselect, segmented, remote-sites).
|
|
- **Settings persistence**: `admin/src/Options/Settings.php` — partial-payload
|
|
save via `merge_on_save()` sanitize callback (merges into existing option,
|
|
doesn't overwrite). `Settings::get_safe()` strips `license_key` and remote
|
|
site passwords for use on non-admin-gated pages; `Settings::get()` (full)
|
|
only used on the manage_options-gated settings page itself.
|
|
- **Global search**: `app/src/shell/components/SearchModal.vue`, Ctrl+K,
|
|
debounced `wp/v2/search` REST calls, gated on `disable_global_search` setting.
|
|
- **Remote site switcher**: toolbar dropdown, gated on `canSwitchSites` (from
|
|
`remote_site_switcher_capability` setting) + non-empty `remote_sites`.
|
|
- **Scheduled content**: `app/src/pages/dashboard/cards/ScheduledContent.vue`
|
|
calendar cells (squares, date top-left, count centered) are clickable —
|
|
navigate to `edit.php?post_status=future&aurora_day=YYYY-MM-DD` if that day
|
|
has scheduled posts, else show a toast ("no scheduled content"). Server side:
|
|
`admin/src/Posts/ScheduledDayFilter.php` filters the `edit.php` query via
|
|
`pre_get_posts` and prints an info notice.
|
|
- **Analytics**: `admin/src/Analytics/Analytics.php` (first-party pageview
|
|
tracker, own DB table `wp_aurora_admin_pageviews`, bot detection, gated on
|
|
`enable_analytics`/`track_admins` settings) + `admin/src/Rest/AnalyticsData.php`
|
|
(aggregation REST endpoint: totals, series, device/referrer/country
|
|
breakdowns, bounce rate, active users).
|
|
- **White label**: `admin/src/WhiteLabel/WhiteLabel.php` — custom favicon,
|
|
rename plugin in Plugins list, rename top-level menu item, gettext
|
|
find/replace via `text_replacements` setting.
|
|
- **Native page dark styling**: `admin/assets/native-dark.css` (large static
|
|
sheet, all rules gated `html.aurora-dark.aurora-ready`, scoped under
|
|
`#wpbody-content`) + `admin/assets/native-enhance.js` (progressive JS
|
|
enhancement — currently only `enhanceUpdates()`, which groups the flat
|
|
Updates page sections into `.aurora-native-card` wrapper divs on
|
|
`body.update-core-php`).
|
|
|
|
## Key bugs fixed (root causes, in case they resurface)
|
|
|
|
- **`.card` global class collision**: original Dashboard cards used
|
|
`class="card"`, colliding with WP core's `.card { max-width: 520px }`,
|
|
capping card width regardless of grid span. Fixed by renaming to
|
|
`.aurora-card*` everywhere. Lesson: never use unprefixed class names on
|
|
Aurora components — always prefix `aurora-`.
|
|
- **Grid-column not applying on wrapped cards**: settled on unwrapped
|
|
`<section class="aurora-card" :style="{gridColumn: ...}">` — component
|
|
boundaries ate the style binding in earlier attempts.
|
|
- **Two-box settings layout**: took two wrong iterations (splitting
|
|
header/fields instead of nav/content) before matching the user's reference
|
|
image. If revisiting settings layout, re-confirm against a screenshot
|
|
before assuming intent.
|
|
- **Redundant outer frame border on settings page**: `#wpbody-content`'s
|
|
frame border/radius doubled up with the new two-box layout; fixed with a
|
|
`body.toplevel_page_aurora-admin` override in `shell-frame.css` that drops
|
|
the outer frame there only.
|
|
|
|
## Current / in-progress task
|
|
|
|
**User's last request: "now the updates page doesn't match the style as the
|
|
dashboard page."**
|
|
|
|
Status: diagnosis started but not finished. I navigated to
|
|
`update-core.php` and confirmed the page renders with the shell (minify
|
|
button, View Website/Dashboard icons, search, dark toggle) and that
|
|
`native-enhance.js` is already grouping the page into three
|
|
`.aurora-native-card` boxes (Current version / Plugins / Themes). I had
|
|
**not yet** done a side-by-side computed-style comparison against
|
|
`.aurora-card` (used on the Dashboard, e.g. "Recent content" / "Site Health"
|
|
cards) to find the actual mismatch — could be background shade, border
|
|
radius, padding, title typography, or hover state. No code changes made yet
|
|
for this specific request.
|
|
|
|
### Next step (concrete)
|
|
|
|
Via Chrome `javascript_exec`, pull `getComputedStyle()` for a live
|
|
`.aurora-card` element on the Dashboard and a live `.aurora-native-card`
|
|
element on the Updates page — compare `background-color`, `border-color`,
|
|
`border-radius`, `padding`, `box-shadow`, and heading font-size/weight. Then
|
|
patch `.aurora-native-card` rules in `admin/assets/native-dark.css` (and/or
|
|
structure in `native-enhance.js` if the mismatch is structural, e.g. missing
|
|
a title wrapper element) to match `.aurora-card` in `Dashboard.vue`. Verify
|
|
live, then rebuild/sync to dist, re-zip, and have the user reinstall.
|
|
|
|
## Not-yet-done (deferred, no active request)
|
|
|
|
- Full field sets for settings categories beyond General/Analytics/White
|
|
Label (original plugin had more).
|
|
- Extending `native-enhance.js` boxing to other native screens (Tools, etc.)
|
|
beyond Updates.
|
|
- Porting the real license-key activation flow (built previously in the old
|
|
`aurora-admin-working` project, not yet ported to v2 — currently just a
|
|
text field).
|
|
- Light-mode boxing for native pages (`native-dark.css`/`native-enhance.js`
|
|
currently only styled for dark mode; light mode native pages are untouched
|
|
WP default).
|