feat: add PlacementController to Gen2

[rubencarvalho]

Description

Adds PlacementController — a Lit reactive controller that positions a floating element relative to a trigger using Floating UI's computePosition + autoUpdate. It's the 2nd-gen replacement for the 1st-gen PlacementController baked into <sp-overlay>, but extracted from the overlay lifecycle so popover, picker, menu, tooltip, coachmark, etc. can each compose it without inheriting overlay machinery.

The controller is the first 2nd-gen primitive that downstream popover-shaped components will use for positioning.

Public API

import { PlacementController } from '@spectrum-web-components/core/controllers/placement-controller';

class MyPopover extends LitElement {
  private placement = new PlacementController(this);

  open(): void {
    this.placement.start(this.trigger, this.panel, {
      placement: 'bottom-start',
      offset: 8,
      shouldFlip: true,
      onPlacementChange: (p) => {
        this.actualPlacement = p;
      },
    });
  }

  close(): void {
    this.placement.stop();
  }
}

Member	Description
start(trigger, floating, options?)	Begin positioning; tear down any prior session and subscribe to autoUpdate.
stop()	Tear down positioning, clear inline max-height / max-width written by size and the tip styles written by arrow, reset state. Called automatically from hostDisconnected.
recompute()	Force one computePosition pass outside autoUpdate.
actualPlacement	Readonly. Computed placement after flip (hyphenated), or null when stopped. Refreshed on every compute.
isConstrained	Readonly. true while size middleware is applying max-height because content would otherwise overflow.

Options: placement (22 hyphenated values including logical start / end), offset, crossOffset, containerPadding, shouldFlip, tipElement, tipPadding, onPlacementChange.

VirtualTrigger is supported — any { getBoundingClientRect(); contextElement? } shape works as the anchor.

Behavioural parity with 1st-gen

Where the controller's behaviour is observable to consumers, it matches 1st-gen:

• Middleware order is the same: offset → shift → flip → size → arrow. shift runs before flip so the panel slides along the current side before any decision to flip; size runs after the final placement is known; arrow runs last (only when a tipElement is provided) so it positions the tip after every other middleware has settled.
• size middleware always installed. Writes max-width on every compute. Writes max-height only when content would otherwise overflow — the controller tracks an initialHeight baseline from the first un-constrained compute (1st-gen's pattern) to detect when content is currently being clamped, and exposes that as isConstrained.
• arrow middleware (opt-in via tipElement) positions a caller-provided tip so it points at the trigger's center, inset from the panel corners by tipPadding. After every compute it pins the tip to the relevant floating edge (top / left) and writes inline translate to slide it along that edge; the tip styles are cleared on stop().
• iOS WebKit visualViewport listeners + offset compensation for URL-bar collapse / pinch-zoom / virtual-keyboard scenarios.
• DPR rounding (roundByDPR) so translated coordinates stay sharp on high-DPR displays.
• document.fonts.ready await + WebKit rAF wait before measuring.
• Fallback-placement table for virtual triggers.

Where the controller intentionally diverges from 1st-gen

These are scope changes, not behaviour changes. They were called out and confirmed in the popover migration plan:

Area	1st-gen	2nd-gen
Scope	Overlay lifecycle + ARIA + positioning	Geometry only
autoUpdate channels	Two channels (one closed the overlay on ancestor scroll)	One channel — just repositions. Caller decides whether ancestor scroll should close the surface.
DOM mutation on trigger	Wrote placement / actual-placement attributes on host elements	None. Computed placement surfaces via the actualPlacement property and onPlacementChange callback.
Host coupling	Required host.elements: OpenableElement[]	Plain ReactiveControllerHost
sp-update-overlays global event	Listened to it for reflow triggers	Removed. The caller invokes recompute() directly when needed.
placeOverlay(target, options)	Single async method	Split into start(trigger, floating, options) / stop() / recompute() with separated lifecycle.
Options shape	OverlayOptionsV1 (abortPromise, delayed, notImmediatelyClosable, receivesFocus, root, type, …)	PlacementOptions — positioning fields only (including tipElement / tipPadding for arrow support). Trigger is a separate first argument.
Offset shape	number | [number, number] (array for multi-axis)	Separate offset and crossOffset fields.

Public API additions

• Placement union (22 values including logical start / end and physical sub-alignment variants), exported with ALL_PLACEMENTS list.
• VirtualTrigger interface.
• PlacementOptions interface, including tipElement / tipPadding for opt-in arrow middleware.
• Pure conversion helpers toFloatingPlacement / fromFloatingPlacement — exported and unit-tested. The SWC Placement union doesn't map 1:1 to Floating UI's 12 values; these bridge the two:
  • Logical sides (start, end) → physical sides (left, right)
  • Logical sub-alignments (start-top, end-bottom) → Floating UI's start / end suffixes on the resolved physical side
  • Physical alignments (bottom-left, left-top) → Floating UI's start / end suffixes
  • Reverse: Floating UI's left-start / left-end / right-start / right-end (not in the SWC union) map back to left-top / left-bottom / right-top / right-bottom

Storybook

Docs page at Controllers / Placement controller with the playground, behavioral demos (requested placement, offset / cross-offset, container padding, should-flip, size-always-clamps, on-placement-change, virtual trigger, arrow), and an inline API table. All 14 stories tagged appropriately for the new core-controller documentation template.

Motivation and context

This is the first geometry primitive shared across the 2nd-gen popover-shaped components. Splitting it out of the 1st-gen overlay model lets popover, picker, menu, tooltip, coachmark, etc. each own their open/close lifecycle and ARIA wiring, while positioning math is centralised here. Aligns with the popover migration plan (CONTRIBUTOR-DOCS/03_project-planning/03_components/popover/migration-plan.md).

Related issue(s)

• SWC-1996

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed the Accessibility Practices for this feature.
• I have added automated tests to cover my changes.
• I have included a well-written changeset if my change needs to be published. (internal-only controller for now; no changeset)
• I have included updated documentation if my change required it.

Reviewer's checklist

• Includes a Github Issue with appropriate flag or Jira ticket number without a link
• Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
• Automated tests cover all use cases and follow best practices for writing
• Validated on all supported browsers
• All VRTs are approved before the author can update Golden Hash

Manual review test cases

• Storybook docs page renders cleanly

  1. Open Storybook → Controllers / Placement controller
  2. Expect a docs page with Overview, Usage, Behaviors (Requested placement, Offset, Container padding, Should flip, Size always clamps, On placement change, Virtual trigger, Arrow), API, Accessibility, and Appendix sections
  3. No "Component not found in manifest" warnings should surface for controller stories

• Playground reacts to every option

  1. Open the Playground story
  2. Toggle each option (placement, offset, cross-offset, container padding, should-flip) and confirm the floating panel responds immediately

• Offset demo shows the difference

  1. Open Behaviors → Offset
  2. Compare the default (8 px) and 48 px variants; the larger-offset panel sits visibly further from the trigger
  3. Same check for crossOffset in the lower row

• Size always clamps the list

  1. Open Behaviors → Size always clamps
  2. The 24-item list is visibly clamped; host.floatingEl.style.maxHeight reads as a numeric px value
  3. host.isConstrained is true

• Arrow tip points at the trigger

  1. Open Behaviors → Arrow
  2. The triangular tip on the floating panel points at the trigger's center
  3. Resize the surface so the panel shifts to stay inside the viewport; the tip continues to point at the trigger's center (inset from the panel corners by tipPadding)

• Virtual trigger follows clicks

  1. Open Behaviors → Virtual trigger
  2. Click anywhere inside the 320×320 surface
  3. The floating panel repositions near the click point with a 12 px offset; coordinates in the panel update

• 29 placement-controller unit tests pass

  1. From 2nd-gen/packages/swc, run yarn test "core/controllers/placement-controller"
  2. All 29 tests should pass — covers conversion functions, all options, flip behaviour both ways, size middleware lifecycle, arrow tip positioning, rapid start() replacement, and disconnect cleanup

Device review

• Did it pass in Desktop?
• Did it pass in (emulated) Mobile? — iOS WebKit visualViewport compensation is included; verify popovers don't drift when toggling the simulated URL bar
• Did it pass in (emulated) iPad?

Accessibility testing checklist

The controller handles geometry only — it does not manage focus, ARIA, or keyboard dismissal. Consumer components remain responsible for accessible open/close behaviour. There is no UI to test against directly.

• Keyboard — N/A. No focusable parts in the controller itself; consuming components wire their own keyboard handling.
• Screen reader — N/A. The controller writes top / left / translate inline styles only (on the floating element and, when provided, the tip element); no roles, names, or live regions. Consumers attach aria-controls, aria-expanded, and labelling as appropriate.

Accessibility guidance for consumers is documented in the Storybook Accessibility story (under Controllers / Placement controller).

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9a3cca8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview Links

• Documentation Site (first-gen)
• Storybook (first-gen)
• Storybook (second-gen)

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6337

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.