V1 Web PWA · Surface walkthrough

Studio · Complex Interaction Patterns

A per-surface walkthrough of the V1 Web PWA studio surface: layout, states, interactions, data, and cross-references.

walked + e2e-covered
9sections3 minread
Markdown source
On this page

Context. surface studio · domain design · route /studio/complex-interactions · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/complex-interactions/page.tsx

Last walked. 2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data (2xx), console/page-errors, expected content, screenshot verified; live screen-reader, touch, offline, and telemetry-delivery checks pending a manual AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body re-derived 2026-06-03 from current source (lane-console architecture); 2026-07-02 studio-design-lane-consoles Playwright pass covers live BFF catalog/resolve, auth/schema gates, error states, focus-order result, quick actions, and mobile no-overflow.

Purpose#

Resolve keyboard focus order with the real resolver: the Focus Order Lane computes the Tab traversal (positive tabindex first, then DOM order, skipping disabled/hidden/negative elements) and flags the positive-tabindex anti-pattern. It is a live admin console wired to /v1/admin/studio/focus-order, not an in-page simulation.

Entry points#

  • Direct URL / bookmark — /studio/complex-interactions (signed-in + studio entitlement; admin scope required to resolve)
  • Sibling Studio routes — reached via the quick-action panel on color-system, component-primitives, design-language, and other design/governance pages

Layout regions#

page.tsx mounts <ShellLayout active="studio"> and renders <StudioComplexInteractionPatternsWorkspace /> followed by a single panel of quick-action links.

  • Shell: ShellLayout chrome with the Studio tab active
  • Workspace heading: WorkspaceHeading renders the page <h1> "Studio Complex Interaction Patterns", followed by the data-complex-interactions-summary paragraph
  • Focus Order Lane: an <h2> data-fo-lane-heading ("Focus Order Lane") section with the load states and, when ready, the resolve form and result table
  • Quick-actions panel: 16 sibling quickAction Links — Navigation/Commands, Search/Discovery, Cross-Domain Entity Model, Workspace Context Switching, Multi-Project Operations, Authentication Architecture, Session and Device Management, RBAC and Permission Policy UX, Enterprise Tenant Isolation, Audit and Compliance Surfaces, Notification Center, Activity and Change Feeds, "Back to Component Primitives workspace", "Back to Spacing/Layout workspace", "Back to Color System workspace", and "Back to Typography workspace". No self-link and no Route Map panel.

States#

  • Loading — data-fo-loading ("Loading focus-order resolver…")
  • Unauthorized — data-fo-unauthorized ("Access restricted.") on 401/403
  • Error — data-fo-error ("Could not load the focus-order resolver.")
  • Ready / form — data-fo-enums ("N issue codes") plus the data-fo-form resolve form
  • Result — data-fo-result headline (data-fo-headline with data-fo-order, data-fo-positive-count) and the data-fo-elements table of data-fo-element-row rows (data-fo-tab-position, data-fo-element-issues)
  • Resolve error — data-fo-resolve-error for invalid JSON or a non-200 response

Interactions#

  • Elements (JSON) — textarea data-fo-payload, aria-label="focus elements json", seeded with { elements[{ elementId, tabIndex, disabled, visible }] }
  • Resolve focus order — button data-fo-submit (type="submit"); POSTs the parsed JSON to /v1/admin/studio/focus-order/resolve, setting data-fo-result on a 200 with a valid result, or data-fo-resolve-error otherwise
  • Quick-action links — each quickAction Link navigates to its sibling Studio route (see Layout regions for the 16 targets)

E2E coverage#

Coverage depth: deep.

  • studio-design-lane-consoles.spec.ts drives /studio/complex-interactions through the live catalog, malformed-JSON client guard, real BFF 400 validation detail, focus-order resolution with positive-tabindex issue surfacing, exact quick-action href list, loading / unauthorized / malformed-catalog fail-closed states, mobile no-overflow, and direct BFF 401 / 403 / 400 gates.

Data & contracts#

  • Reads: GET /v1/admin/studio/focus-order on mount — returns the catalog (issues[])
  • Writes: POST /v1/admin/studio/focus-order/resolve — returns { result: { focusOrder[], elements[], summary{ focusableCount, positiveTabindexCount } } }
  • Realtime: none
  • Caching: client fetch with cache: 'no-store'; buildBffAuthHeaders() attaches the bearer token
  • Auth/role check: admin-scoped fail-closed — admin:* or admin:studio, 401/403 under the studio workspace gate

Cross-references#

Known downstream boundaries#

  • Current source intentionally uses the flat quick-action panel and no Route Map panel; the 2026-07-02 browser spec asserts the exact target list.
  • The current resolver contract is Tab focus order plus the positive_tabindex issue. Future transition or recovery lanes should get new route contracts and walkthrough rows when they ship.