Initial commit: Aurora Admin plugin
This commit is contained in:
Kris Parish
@@ -0,0 +1,148 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user