# ACF Field Translation Master–Detail Redesign — request

**Goal:** Replace the accordion-first ACF Fields page with a responsive, accessible master–detail workspace that preserves hierarchy, translation policy, cached loading, and exact working context during refresh.

**Context:** The current route in `admin/src/pages/fields-translate.js` renders searchable field-group accordions backed by canonical store `acf-fields:all`, `DataRegion`, layered browser/plugin caching, keyed reconciliation, nested lazy disclosures, and immediate policy PATCH mutations. Preserve these contracts while adopting the owner-approved design in `docs/specs/2026-08-12-acf-master-detail-redesign-design.md`. Visual target: `/home/user/.claude/image-cache/d48c7b7a-60b2-460d-92b1-7567807256fb/1.png`.

**Files:**
- Modify `admin/src/pages/fields-translate.js` — master/detail rendering, route state, search/filter, hierarchy, reconciliation, responsive flow, focus/scroll restoration.
- Modify `admin/src/main.js` — parse hash path/query separately and retain mounted Fields route for same-route group history changes.
- Modify `admin/src/styles/pages/_translations.scss` — token-based two-pane, card, row, skeleton, responsive drill-in, dark-mode, focus, reduced-motion styles.
- Modify `includes/Compatibility/ACFIntegration.php` — expose normalized group location summaries and native layout keys when available.
- Modify `includes/API/ACFFieldsController.php` only where response normalization/contract requires it.
- Modify focused JS, PHP, and E2E tests covering changed contracts; rename accordion-specific tests/journey when their primary contract changes.
- Rebuild tracked `admin/dist/` production assets.

**Response contract:**
- Existing `GET /translations/fields` route remains.
- Each group adds `locations: Array<{ label: string, ruleCount: number }>` normalized from ACF location rules.
- Each flexible-content layout exposes native ACF `key` when available.
- Layout identity uses native key; legacy fallback is `layout:<parent-field-key>:<layout-name>`.
- Increment existing ACF-fields cache schema/version when response shape requires invalidating incompatible snapshots.
- Existing global-default and per-field PATCH routes and real policy vocabulary remain authoritative.

**Routing contract:**
- Canonical selection URL: `#/translations/fields?group=<stable-acf-group-key>`.
- Router resolves path `translations/fields` separately from query.
- Card selection pushes history; reconciliation fallback replaces history.
- Back/Forward changes selection without destroying/recreating the mounted Fields page.
- Unrelated route changes preserve existing teardown.
- No URL key selects first group on wide/medium screens; narrow screens start on master unless a valid URL key exists.
- A disappeared selection resolves to item at its prior index, then previous final item when out of range, then first item; announce the change.

**Master behavior:**
- Compact field-group cards only; never individual-field cards.
- Search title, group key, normalized locations, and descendant field label/name/type/key.
- Filters: All and Custom overrides. Add no Needs review/warning/unsupported filter without an exact tested response predicate.
- Cards show title, recursive editable field count, location summary, inherited/override summary, and selected marker.
- Recursive override count includes editable descendants with explicit policy; layout/read-only nodes do not count.
- Use semantic list plus real buttons, `aria-current="true"`, visible non-color-only selected state, Arrow-key focus movement, Enter/Space selection.
- If search/filter hides selected group, retain selection and expose a clear selected-hidden affordance.

**Detail behavior:**
- Header shows group title, key, field count, location summary, policy summary.
- Global default stays in page header and explains per-field overrides.
- Separate field search covers label, name, key, and type; filters are All and Overrides unless other exact predicates exist.
- Semantic dense table/list columns: Field, Type, Source, Translation mode, Status.
- Show inherited versus explicit override directly using existing policy vocabulary.
- Preserve nested repeater/group/flexible-content/layout hierarchy by stable keys; layout-only rows are read-only; closed branches do not mount descendants.
- Preserve current global mutation queue and global control lock. Success invalidates/revalidates; failure rolls back and retains full UI state.
- Do not add Add Field, pagination, drag/drop, fake status, unsupported bulk actions, or new policy values.

**State and reconciliation:**
- Preserve selected group, master search/filter, detail search/filter, open hierarchy keys, master scroll, document/detail scroll, and logical focus during revalidation and mobile Back.
- Revalidate by stable keys without page rebuild, disclosure closure, search clearing, valid-selection change, scroll/focus reset, or overwrite of in-progress edit.
- Focus fallback: exact field → owning disclosure → selected-group heading → master heading.
- Persist no saving state, transient error, dialog, nonce, authentication, licensing, payment, migration, or live-job data.
- Retain existing canonical store, `DataRegion`, browser snapshot, WordPress database snapshot, TTL, permission, partition, invalidation, duplicate-refresh, and last-valid-snapshot contracts unless a focused test proves an acceptance gap.

**Responsive and visual behavior:**
- Max workspace width near 1440px; wide master near 320px; detail minimum near 560px; gap 20–24px.
- Use existing admin breakpoint tokens. Medium master 260–300px; hide secondary metadata before field controls; only table wrapper may scroll horizontally.
- Narrow breakpoint uses drill-in master → detail with “Back to field groups”; never stacks both long panes.
- Document owns vertical scroll. Preserve master scroll on return.
- Cold skeleton mirrors two-pane cards/rows and respects reduced motion.
- Cached data replaces skeleton immediately. Refresh failure retains content with exact notice: `Showing saved data. The latest refresh could not be completed.` Notice clears after successful refresh/retry.
- Use existing design tokens/components, subtle borders/elevation, existing theme dark-mode controller, no inline CSS, no hard-coded colors.

**Accessibility:**
- Semantic headings, navigation/list, table/structured list, captions/labels, real buttons, `aria-current`, `aria-expanded`, `aria-controls`, live announcements, visible focus, WCAG AA contrast, practical 44px targets, reduced motion.
- Every action is keyboard accessible. Revalidation preserves focus by stable key.

**Out of scope:**
- Translation-policy redesign; new cache service; server-side search/pagination; field creation; drag/drop; decorative analytics; unrelated admin refactors; replacement API routes; sensitive/live endpoint caching.

**Acceptance:**
- Run focused admin JS tests including group selection, history, searches/filters, stable identities, nested lazy disclosures, source display, read-only rows, successful save, rollback, state retention, loading/cached/stale/empty/error states, and cleanup. Expected: clean PASS with no warnings.
- Run focused PHP/controller/cache contract tests for location/layout response additions and cache schema isolation. Expected: clean PASS; established miss/hit/stale/invalidation behavior remains green.
- Run `cd admin && npm run build`. Expected: clean production build and updated tracked assets without warnings.
- Run browser verification only through `e2e-remote` against local WordPress in Chromium and Firefox. Prove desktop master–detail, narrow drill-in/back, skeleton-to-cache transition, URL/history, keyboard navigation, disclosures, safe save/rollback, focus/scroll retention, warm navigation, no runtime/accessibility failures.
- Capture before/after screenshots and verify layout/computed styles against the supplied reference.
- Run project release gates from `.claude/agents/expert.md` and loaded skills. Every warning/finding must be fixed or explicitly proven benign before commit.

## Responsive Overflow Fix — ACTIVE

**Task ID:** responsive-overflow-acf-master-detail

**Source request:** Fix verified horizontal document overflow at widths 783–843px. Existing medium grid requires `260px + 560px + 24px` while narrow drill-in begins only below `782px`.

**Outcome:** At every viewport width, workspace must fit its available inline space. Wide two-pane and narrow drill-in behavior remain unchanged. Only field-table wrapper may use horizontal scrolling.

**Acceptance delta:**
- Use existing token-based responsive SCSS only; no inline styles, hard-coded colors, or dark-mode/accessibility regression.
- Adjust medium breakpoint/layout so its minimum inline size does not exceed its active viewport range, or enter narrow drill-in before overflow can occur.
- Retain wide master/detail dimensions, narrow master-to-detail drill-in, and table-only horizontal overflow.
- Update narrowest relevant DOM/style test when an existing focused test exposes layout behavior; do not add screenshot assertions to unit tests.
- Run focused ACF Vitest, lint, and `cd admin && npm run build` cleanly.
- Verify computed minimum widths mathematically.
- Stage and commit only `_translations.scss`, relevant focused test if changed, and generated `admin/dist` files including asset-manifest/hash replacements. Commit has no co-author.

**Preserved WIP/ref/path:** Work only in `/home/user/Projects/Press.zone/wordpress/wp-content/.worktrees/acf-page-redesign/plugins/international-press-zone`; preserve all unrelated existing worktree changes.

**Constraints:** No unrelated source or generated-file cleanup. Do not alter generated output except direct rebuild result. Do not create unit-test screenshot assertions.

**Execution steps:**
1. Inspect responsive workspace rules and focused ACF tests.
2. Select token-based breakpoint/layout correction and prove active-range minimum widths.
3. Apply minimal SCSS/test update.
4. Run focused tests, lint, production build, inspect generated asset set.
5. Stage allowed files, commit after all gates are clean.

**Current receipt:** Completed responsive overflow fix in commit `f0185dc6a` (`Fix ACF workspace overflow`). Commit contains only `admin/src/styles/pages/_translations.scss` and generated `admin/dist/css/main.css`; no asset hash replacement was emitted. SCSS uses existing medium 260–300px master plus flexible `minmax(0, 1fr)` detail for live workspace and skeleton. Table wrapper and skeleton columns have `min-width: 0`, so the 640px field table is the sole horizontal-scroll owner. Mathematical proof at 783px and 843px: grid minimum is 260px + 0px + 24px = 284px; skeleton matches. Focused ACF Vitest (27 tests), JavaScript lint, diff check, production build, and pre-commit checks passed cleanly.

**Next executable action:** None for this fix. Continue remaining redesign plan work independently.

## Deterministic ACF Journey Fixture Contract — DONE

**Task ID:** acf-journey-false-skip-contract

**Source request:** Under required deterministic verification journey, empty `fields.groups` fixture is broken test environment. Both UJ-ACF tests MUST fail clearly before group access; they MUST NOT call `test.skip`. Preserve explicit failures for unavailable, malformed, and non-2xx REST responses, live-DOM unit assertion, and REST helper hardening.

**Outcome:** Required ACF browser journeys cannot report skipped/pass when authorized fixture endpoint lacks usable field groups.

**Acceptance delta:**
- Replace both false-skip guards in `tests/e2e/journeys/UJ-ACF-field-table-accordions.spec.js` with clear deterministic assertions/errors before any `fields.groups` access.
- Keep `available === false`, malformed payload, and non-2xx helper responses as explicit failures.
- Run focused Vitest, Node syntax check, and relevant lint cleanly.
- Amend commit `38134e9d5` without changing owned files beyond required test file.

**Preserved WIP/ref/path:** Work only in `/home/user/Projects/Press.zone/wordpress/wp-content/.worktrees/acf-page-redesign/plugins/international-press-zone`; preserve all unrelated existing worktree changes. Base commit was `38134e9d5`.

**Constraints:** Do not weaken required journey assertions or alter REST helper/unit hardening. No generated asset changes.

**Execution steps:**
1. Inspect both journey guards and helper contract.
2. Add explicit fixture assertions before every group access.
3. Run focused Vitest, Node syntax, and lint.
4. Amend `38134e9d5` after clean verification.

**Current receipt:** Completed in amended commit `7c1603786` (`Update ACF field test contracts`). Both required UJ-ACF tests call shared `assertRequiredAcfFixture(fields)` immediately after `getAcfFields()`, before any group access. It asserts `available === true` and non-empty groups with clear fixture-contract messages. `getAcfFields()` continues to throw on non-2xx and malformed responses; live-DOM unit assertion and REST hardening remain in the amended commit. Focused Vitest passed (1 test); `admin` JavaScript lint passed; journey Node syntax passed twice (direct and package-managed); pre-commit checks passed. No warnings were emitted.

**Next executable action:** None for this task. Continue remaining redesign plan work independently.

## Deterministic ACF Journey Fixture Contract — DONE

**Task ID:** acf-journey-false-skip-contract

**Source request:** Review found the second required UJ-ACF journey still contained a `test.skip` fixture guard at line 55. Replace it with the shared `assertRequiredAcfFixture(fields)` assertion before any group access, prove the owned journey has no `test.skip` calls or skip guards, preserve all other repairs, then amend `7c1603786`.

**Acceptance delta:** Both required journeys call the same shared assertion immediately after `getAcfFields()`. The owned journey has zero `test.skip` calls and no conditional skip guard. Focused Vitest, admin lint, and Node syntax complete cleanly. The target commit is amended.

**Preserved WIP/ref/path:** Work occurred only in `/home/user/Projects/Press.zone/wordpress/wp-content/.worktrees/acf-page-redesign/plugins/international-press-zone`; unrelated worktree changes remain preserved.

**Constraints:** REST helper hardening, live-DOM assertion, and all other test repairs remain unchanged. Generated assets were not changed.

**Execution steps:**
1. Replaced the second conditional skip guard with `assertRequiredAcfFixture(fields)` before `fields.groups` access.
2. Inspected the complete owned journey and mechanically verified zero skip calls/guards.
3. Ran focused Vitest, admin lint, and Node syntax.
4. Amended target commit.

**Current receipt:** Completed in amended commit `7d8b19f6b` (`Update ACF field test contracts`). Both required UJ-ACF journeys now call `assertRequiredAcfFixture(fields)` immediately after `getAcfFields()` and before any group access. A complete-file search for `test.skip` and `.skip(` returned no matches. Focused Vitest passed: 1 file, 9 tests. Admin JavaScript lint passed. Node syntax passed. Pre-commit checks passed; informational messages were benign because this staged commit contained no root-level package, PHP, Trivy, or Composer-audit inputs. Existing unrelated worktree changes remain unstaged.

**Next executable action:** Install and verify the ACF redesign in mounted local WordPress.

## Install and Verify ACF Master–Detail Redesign — ACTIVE

**Task ID:** 28 (`Install and verify ACF redesign`).

**Source request:** Safely sync this worktree plugin into mounted local WordPress without deleting unrelated shared-checkout WIP. Preserve generated `tests/e2e/.auth/admin.json` as runtime artifact; do not commit it. Activate/verify ACF, provision canonical deterministic collection-field fixture via existing E2E fixture mechanism, then run focused PHP, all ACF Vitest, full JS lint, production build, asset completeness, Chromium/Firefox remote browser journeys against localhost, and save evidence. No source edits.

**Outcome:** Mounted local WordPress runs this worktree's redesigned plugin with active ACF and deterministic fixture data. Every named required verification gate has clean evidence; any failed or skipped required gate makes acceptance false.

**Acceptance criteria:**
- Runtime plugin sync preserves unrelated files and WIP in shared checkout; runtime has `ACFFieldsController` and current built assets.
- ACF active and canonical deterministic collection-field fixture provisioned through existing E2E mechanism.
- Focused PHP, all ACF Vitest, full JavaScript lint, build, and asset completeness pass cleanly.
- Chromium and Firefox browser journeys run only through `e2e-remote` against `http://localhost:8080`; required hierarchy tests do not skip.
- Evidence covers desktop/mobile, URL/history, keyboard/focus, hierarchy/disclosures, save rollback, console, and accessibility.

**Preserved WIP/ref/path:** Worktree `/home/user/Projects/Press.zone/wordpress/wp-content/.worktrees/acf-page-redesign/plugins/international-press-zone`; mounted runtime `/home/user/Projects/Press.zone/wordpress/wp-content/plugins/international-press-zone`; preserve generated runtime auth state and all unrelated shared-checkout WIP. No source edits.

**Constraints:** No commit. No source edits. Do not delete or overwrite unrelated runtime/shared-checkout files. Required browser test skips are failures.

**Execution steps:**
1. Inspect existing deployment/fixture/test contracts and runtime divergence.
2. Sync only worktree plugin content into mounted runtime, excluding runtime auth artifact; verify controller and asset identity.
3. Activate ACF and provision deterministic collection fixture via existing mechanism.
4. Run deterministic unit/build/asset gates, then remote Chromium and Firefox journeys with saved artifacts.
5. Record every result and exact next action; report acceptance false on any failure or required skip.

**Current receipt:** ACTIVE. No installation or verification result recorded yet.

**Next executable action:** Inspect sync, fixture, test, and evidence mechanisms before runtime mutation.