@mhmo91/schmancy 0.9.28 → 0.10.2

package/src/overlay/overlay.confirm-body.ts

@@ -1,8 +1,9 @@
-import { $LitElement } from '@mixins/index'
-import { css, html, nothing, type TemplateResult } from 'lit'
+import { SchmancyElement } from '@mixins/index'
+import { css, html, type TemplateResult } from 'lit'
 import { customElement, property, query } from 'lit/decorators.js'
 import { when } from 'lit/directives/when.js'
 import { choose } from 'lit/directives/choose.js'
+import { ifDefined } from 'lit/directives/if-defined.js'
 
 /**
  * Internal body component used by the `confirm()` / `prompt()` sugar.
@@ -16,7 +17,8 @@ import { choose } from 'lit/directives/choose.js'
  * callers pass their own component to `show()`.
  */
 @customElement('schmancy-overlay-prompt-body')
-export class SchmancyOverlayPromptBody extends $LitElement(css`
+export class SchmancyOverlayPromptBody extends SchmancyElement {
+	static styles = [css`
 	:host {
 		display: block;
 		padding: 20px 24px;
@@ -31,7 +33,8 @@ export class SchmancyOverlayPromptBody extends $LitElement(css`
 		background: var(--schmancy-sys-color-error, #b3261e);
 		color: var(--schmancy-sys-color-on-error, #ffffff);
 	}
-`) {
+`]
+
 	@property({ type: String }) heading?: string
 	@property({ type: String }) subtitle?: string
 	@property({ type: String }) message?: string
@@ -44,7 +47,18 @@ export class SchmancyOverlayPromptBody extends $LitElement(css`
 	@property({ type: String }) label?: string
 	@property({ type: String, attribute: 'default-value' }) defaultValue = ''
 	@property({ type: String }) placeholder?: string
-	@property({ type: String, attribute: 'input-type' }) inputType: string = 'text'
+	@property({ type: String, attribute: 'input-type' })
+	inputType:
+		| 'text'
+		| 'email'
+		| 'password'
+		| 'tel'
+		| 'url'
+		| 'number'
+		| 'search'
+		| 'date'
+		| 'time'
+		| 'datetime-local' = 'text'
 	@property({ type: String }) pattern?: string
 	@property({ type: Boolean }) required = false
 
@@ -107,8 +121,8 @@ export class SchmancyOverlayPromptBody extends $LitElement(css`
 								<input
 									type=${this.inputType}
 									.value=${this.defaultValue}
-									placeholder=${this.placeholder ?? nothing}
-									pattern=${this.pattern ?? nothing}
+									placeholder=${ifDefined(this.placeholder)}
+									pattern=${ifDefined(this.pattern)}
 									?required=${this.required}
 									class="w-full px-3 py-2 rounded-md border border-outline-variant text-base mb-2"
 								/>

package/src/overlay/overlay.gestures.ts

@@ -3,24 +3,40 @@ import { filter, fromEvent, merge, Observable, Subject, take, takeUntil, tap } f
 /**
  * Swipe-to-dismiss gesture for sheet-layout overlays.
  *
- * RxJS-native (rxjs skill principle 3: every async source is an Observable).
- * Returns an Observable that emits `'dismiss'` when the gesture passes the
- * distance/velocity threshold. Caller maps emissions to teardown.
+ * Pointer-event based — a single pipeline covers touch, mouse, pen, and
+ * any future pointer source. Without a visible drag handle, the gesture
+ * only starts within the top DRAG_START_TOP_PX band of the surface (a
+ * standard pull-to-dismiss convention). Escape + backdrop click cover
+ * the non-pointer dismiss paths via the component's modal-tier listeners.
  *
+ * RxJS-native (rxjs skill principle 3: every async source is an Observable).
  * Thresholds are policy constants, not magic numbers.
  */
 
-/** Distance beyond which the gesture dismisses, in px. */
+/** Distance (px) past which the gesture dismisses. */
 export const DISMISS_DISTANCE_PX = 80
-/** Distance beyond which the gesture dismisses, as a fraction of sheet height. */
-export const DISMISS_DISTANCE_FRACTION = 0.3
-/** Velocity beyond which the gesture dismisses, in px per ms. */
-export const DISMISS_VELOCITY_PX_PER_MS = 0.5
-/** Drag only starts if touchstart is within this top-px band (unless a drag handle is used). */
+/** Distance as fraction of sheet height past which the gesture dismisses. */
+export const DISMISS_DISTANCE_FRACTION = 0.25 // Vaul's value — feels right.
+/** Velocity (px/ms) past which the gesture dismisses even short of distance. */
+export const DISMISS_VELOCITY_PX_PER_MS = 0.4 // Vaul's value.
+/** Drag only starts if pointerdown is within this top band (unless a drag handle is used). */
 export const DRAG_START_TOP_PX = 40
-/** Snap-back spring duration when gesture doesn't pass threshold. */
+/** Snap-back animation duration when gesture doesn't pass threshold. */
 export const SNAP_BACK_MS = 300
 
+/**
+ * Logarithmic rubber-band damping for upward (negative) drag past the
+ * top detent. Pulled from Vaul — `8 * (log(v + 1) - 2)` — diminishing
+ * returns that feel physical, unlike the linear × 0.2 this replaces.
+ *
+ * Applied only to upward motion; downward drag tracks 1:1.
+ */
+export function logDamp(delta: number): number {
+	if (delta >= 0) return delta
+	const abs = -delta
+	return -Math.max(0, 8 * (Math.log(abs + 1) - 2))
+}
+
 export interface SwipeInputs {
 	/** The surface element to track gestures on. */
 	surface: HTMLElement
@@ -32,13 +48,11 @@ export interface SwipeInputs {
 }
 
 /**
- * Returns an Observable that emits exactly once when the user commits to
- * dismissing the sheet (threshold passed). The gesture is owned by the
- * caller — teardown fires on unsubscribe.
- *
- * During an in-progress drag, the surface's `transform` is updated
- * directly for 1:1 tracking. On release-but-not-dismissed, the surface
- * snaps back via a CSS transition.
+ * Emits exactly once when the user commits to dismissing the sheet
+ * (distance OR velocity threshold passed). Works for touch, mouse, and
+ * pen via the Pointer Events API. During an in-progress drag the
+ * surface's `transform` is updated directly for 1:1 tracking. On
+ * release-but-not-dismissed, the surface snaps back via a CSS transition.
  */
 export function swipeToDismiss$(inputs: SwipeInputs): Observable<'dismiss'> {
 	const { surface, dragHandle, until$ } = inputs
@@ -48,62 +62,83 @@ export function swipeToDismiss$(inputs: SwipeInputs): Observable<'dismiss'> {
 		const stopCurrent$ = new Subject<void>()
 
 		let dragging = false
+		let activePointerId: number | null = null
 		let startY = 0
 		let startTime = 0
 		let currentDelta = 0
 
-		const touchStart$ = fromEvent<TouchEvent>(dragTarget, 'touchstart', { passive: true }).pipe(
-			// Pinch-zoom guard — only single-finger drags dismiss.
-			filter((e) => e.touches.length === 1),
-			// If no drag handle, require start within the top band.
+		const pointerDown$ = fromEvent<PointerEvent>(dragTarget, 'pointerdown').pipe(
+			// Primary button / primary finger only. For touch, isPrimary also
+			// covers the pinch-zoom guard (only one finger has isPrimary=true).
+			filter((e) => e.isPrimary && (e.pointerType !== 'mouse' || e.button === 0)),
+			// Without a dedicated drag handle, require start in the top band.
 			filter((e) => {
 				if (dragHandle) return true
-				const touch = e.touches[0]
 				const rect = surface.getBoundingClientRect()
-				return touch.clientY - rect.top <= DRAG_START_TOP_PX
+				return e.clientY - rect.top <= DRAG_START_TOP_PX
 			}),
 			tap((e) => {
 				dragging = true
-				startY = e.touches[0].clientY
+				activePointerId = e.pointerId
+				startY = e.clientY
 				startTime = performance.now()
 				currentDelta = 0
 				surface.style.transition = 'none'
 				surface.style.willChange = 'transform'
+				// Capture so pointermove fires even if the pointer leaves the element
+				// (covers the "drag from handle, move past surface edge" case).
+				try {
+					;(dragTarget as Element).setPointerCapture?.(e.pointerId)
+				} catch {
+					// setPointerCapture can throw on detached elements; safe to ignore.
+				}
 			}),
 		)
 
-		const touchMove$ = fromEvent<TouchEvent>(surface, 'touchmove', { passive: false }).pipe(
+		const pointerMove$ = fromEvent<PointerEvent>(dragTarget, 'pointermove').pipe(
 			filter(() => dragging),
-			filter((e) => e.touches.length === 1),
+			filter((e) => e.pointerId === activePointerId),
 			tap((e) => {
-				const deltaY = e.touches[0].clientY - startY
-				// Rubber-band on upward drag.
-				currentDelta = deltaY < 0 ? deltaY * 0.2 : deltaY
+				const deltaY = e.clientY - startY
+				currentDelta = logDamp(deltaY)
 				surface.style.transform = `translateY(${currentDelta}px)`
-				e.preventDefault()
+				// preventDefault is a no-op on default Pointer Events but avoids
+				// accidental text selection / page scroll during the drag.
+				if (e.cancelable) e.preventDefault()
 			}),
 		)
 
-		const touchEnd$ = merge(
-			fromEvent<TouchEvent>(surface, 'touchend', { passive: true }),
-			fromEvent<TouchEvent>(surface, 'touchcancel', { passive: true }),
+		const pointerEnd$ = merge(
+			fromEvent<PointerEvent>(dragTarget, 'pointerup'),
+			fromEvent<PointerEvent>(dragTarget, 'pointercancel'),
+			fromEvent<PointerEvent>(dragTarget, 'lostpointercapture'),
 		).pipe(
 			filter(() => dragging),
+			filter((e) => e.pointerId === activePointerId),
 			tap(() => {
 				dragging = false
+				const pointerId = activePointerId
+				activePointerId = null
+				try {
+					if (pointerId !== null) (dragTarget as Element).releasePointerCapture?.(pointerId)
+				} catch {
+					// same reason as setPointerCapture — ignore.
+				}
+
 				const elapsed = Math.max(1, performance.now() - startTime)
 				const velocity = currentDelta / elapsed
 				const surfaceHeight = surface.getBoundingClientRect().height
 				const distanceThreshold = Math.min(DISMISS_DISTANCE_PX, surfaceHeight * DISMISS_DISTANCE_FRACTION)
 
 				const shouldDismiss =
-					currentDelta > distanceThreshold || (currentDelta > 20 && velocity > DISMISS_VELOCITY_PX_PER_MS)
+					currentDelta > distanceThreshold ||
+					(currentDelta > 20 && velocity > DISMISS_VELOCITY_PX_PER_MS)
 
 				surface.style.willChange = ''
 
 				if (shouldDismiss) {
 					// Finish translate off-screen for visual continuity with the dismiss
-					// animation; the caller's teardown will then unmount.
+					// animation; the caller's teardown will unmount.
 					surface.style.transition = `transform ${SNAP_BACK_MS}ms cubic-bezier(0.16, 1, 0.3, 1)`
 					surface.style.transform = 'translateY(100%)'
 					subscriber.next('dismiss')
@@ -116,7 +151,7 @@ export function swipeToDismiss$(inputs: SwipeInputs): Observable<'dismiss'> {
 			}),
 		)
 
-		merge(touchStart$, touchMove$, touchEnd$)
+		merge(pointerDown$, pointerMove$, pointerEnd$)
 			.pipe(takeUntil(merge(stopCurrent$, until$)))
 			.subscribe()
 
@@ -129,3 +164,4 @@ export function swipeToDismiss$(inputs: SwipeInputs): Observable<'dismiss'> {
 		}
 	}).pipe(take(1))
 }
+

package/src/overlay/overlay.layout.ts

@@ -1,4 +1,4 @@
-import type { Anchor, OverlayLayout } from './overlay.types'
+import type { Anchor, OverlayLayout, VirtualAnchor } from './overlay.types'
 
 /**
  * Layout dispatch engine — pure function of (anchor, content, viewport).
@@ -74,3 +74,105 @@ export function readViewport(): LayoutInputs['viewport'] {
 		isCoarsePointer: window.matchMedia('(pointer: coarse)').matches,
 	}
 }
+
+/**
+ * Resolved reference the positioning strategies consume.
+ *
+ * `el` is populated when the anchor is an HTMLElement — the Popover API
+ * tier uses it directly via the `anchor=<id>` attribute, and Tier 1 / CSS
+ * Anchor Positioning sets `element.style.anchorName` on it.
+ *
+ * `virtual` is populated for point/rect/TouchEvent anchors — Floating UI
+ * accepts any object exposing `getBoundingClientRect()` as a virtual
+ * reference. The Popover API path cannot use virtual references, so a
+ * caller passing a point / DOMRect / event forces Tier 3 (or Tier 2 with
+ * Floating UI, not CSS Anchor Positioning).
+ */
+export interface ResolvedAnchor {
+	el?: HTMLElement
+	virtual?: VirtualAnchor
+}
+
+/**
+ * Normalise an `Anchor` input into the shape the positioning strategies
+ * accept. One function, one decision: element wins if present; otherwise
+ * synthesize a zero-size virtual reference at the anchor's point.
+ *
+ * Called by the overlay element during `open()` before dispatching to
+ * `pickPositioner(resolved)`.
+ */
+export function resolveAnchorRef(anchor: Anchor | undefined): ResolvedAnchor | undefined {
+	if (!anchor) return undefined
+
+	// HTMLElement — native element reference.
+	if (typeof HTMLElement !== 'undefined' && anchor instanceof HTMLElement) {
+		return { el: anchor }
+	}
+
+	// Any other object with getBoundingClientRect — treat as virtual.
+	if (typeof (anchor as { getBoundingClientRect?: unknown }).getBoundingClientRect === 'function') {
+		return {
+			virtual: {
+				getBoundingClientRect: () => (anchor as { getBoundingClientRect(): DOMRect }).getBoundingClientRect(),
+			},
+		}
+	}
+
+	// DOMRect — fixed rect; synthesize a virtual that returns it verbatim.
+	if (
+		typeof (anchor as DOMRect).width === 'number' &&
+		typeof (anchor as DOMRect).height === 'number' &&
+		typeof (anchor as DOMRect).left === 'number' &&
+		typeof (anchor as DOMRect).top === 'number'
+	) {
+		const rect = anchor as DOMRect
+		return {
+			virtual: {
+				getBoundingClientRect: () => rect,
+			},
+		}
+	}
+
+	// MouseEvent / PointerEvent — zero-size rect at click point.
+	if (typeof (anchor as MouseEvent).clientX === 'number' && typeof (anchor as MouseEvent).clientY === 'number') {
+		const e = anchor as MouseEvent
+		const rect = makePointRect(e.clientX, e.clientY)
+		return { virtual: { getBoundingClientRect: () => rect } }
+	}
+
+	// TouchEvent — zero-size rect at first touch point.
+	if (
+		typeof (anchor as TouchEvent).touches !== 'undefined' &&
+		(anchor as TouchEvent).touches.length > 0
+	) {
+		const t = (anchor as TouchEvent).touches[0]
+		const rect = makePointRect(t.clientX, t.clientY)
+		return { virtual: { getBoundingClientRect: () => rect } }
+	}
+
+	// { x, y } point — zero-size rect at coords.
+	const pt = anchor as { x: number; y: number }
+	const rect = makePointRect(pt.x, pt.y)
+	return { virtual: { getBoundingClientRect: () => rect } }
+}
+
+/**
+ * Construct a DOMRect-compatible object for a zero-width / zero-height
+ * point. Avoids `new DOMRect(...)` which isn't constructable across all
+ * lib.dom.d.ts vintages.
+ */
+function makePointRect(x: number, y: number): DOMRect {
+	return {
+		x,
+		y,
+		width: 0,
+		height: 0,
+		left: x,
+		right: x,
+		top: y,
+		bottom: y,
+		toJSON() {
+			return { x, y, width: 0, height: 0, left: x, right: x, top: y, bottom: y }
+		},
+	}
+}

package/src/overlay/overlay.positioning.ts

@@ -0,0 +1,301 @@
+import {
+	autoUpdate,
+	computePosition,
+	flip,
+	offset,
+	shift,
+	size,
+	type Placement,
+} from '@floating-ui/dom'
+import { Observable } from 'rxjs'
+import { ANCHOR_FIT_PADDING_PX, type ResolvedAnchor } from './overlay.layout'
+import type { OverlayPlacement, OverlayTier } from './overlay.types'
+
+/**
+ * Three-tier positioning ladder for anchored overlays. Public API of the
+ * overlay doesn't change based on the tier — the strategy is picked
+ * internally by feature-detection.
+ *
+ * Tier 1 — CSS Anchor Positioning (Popover + `anchor-name` / `position-anchor`)
+ *   Zero-JS position tracking. Chromium-only today.
+ *
+ * Tier 2 — Popover API + Floating UI
+ *   Native top-layer + light-dismiss + Esc from `popover="auto"`, Floating
+ *   UI middleware for the position math. Safari 17+, Chrome 114+, Firefox 125+.
+ *
+ * Tier 3 — Floating UI only
+ *   Fallback for browsers without the Popover API. Caller provides manual
+ *   backdrop + click-outside + Esc wiring.
+ */
+
+/**
+ * Feature-detection snapshot captured at module load. Frozen so consumers
+ * can safely destructure and compare.
+ */
+export const CAPS = Object.freeze({
+	popover:
+		typeof HTMLElement !== 'undefined' &&
+		'popover' in HTMLElement.prototype &&
+		typeof (HTMLElement.prototype as unknown as { showPopover?: () => void }).showPopover === 'function',
+	cssAnchor:
+		typeof CSS !== 'undefined' &&
+		typeof CSS.supports === 'function' &&
+		CSS.supports('anchor-name: --x'),
+})
+
+/**
+ * Pick the positioning tier for an anchor.
+ *
+ * CSS Anchor Positioning (Tier 1) requires a real element anchor — you
+ * can't point `anchor-name` at a DOMRect or a coord. A point/rect anchor
+ * forces Tier 2 (or Tier 3 if popover isn't supported).
+ */
+export function pickPositioner(anchor: ResolvedAnchor): OverlayTier {
+	if (CAPS.popover && CAPS.cssAnchor && anchor.el) return 'css-anchor'
+	if (CAPS.popover) return 'popover-fui'
+	return 'fui-only'
+}
+
+/* ======================================================================= *
+ *                   Tier 1 — Popover API + CSS Anchor                      *
+ * ======================================================================= */
+
+/**
+ * Set up CSS Anchor Positioning. Assigns a unique `anchor-name` to the
+ * anchor element and injects a stylesheet into the shadow root that
+ * positions the surface relative to it. No JS running per frame.
+ *
+ * Returns a cleanup function that removes the injected styles and the
+ * anchor-name from the anchor element.
+ */
+export function positionCSSAnchor(
+	surface: HTMLElement,
+	anchor: ResolvedAnchor,
+	shadowRoot: ShadowRoot,
+	opts: { id: string; placement?: OverlayPlacement } = { id: '' },
+): () => void {
+	if (!anchor.el) {
+		throw new Error('positionCSSAnchor requires an element anchor')
+	}
+	const anchorEl = anchor.el
+	const anchorName = `--ov-${opts.id || Math.random().toString(36).slice(2, 10)}`
+	const placement = opts.placement ?? 'bottom-start'
+
+	// Save any prior anchor-name so we can restore it on cleanup.
+	const priorAnchorName = anchorEl.style.getPropertyValue('anchor-name')
+	anchorEl.style.setProperty('anchor-name', anchorName)
+
+	const sheet = new CSSStyleSheet()
+	sheet.replaceSync(`
+		${surface.localName}[data-overlay-ref="${opts.id}"] {
+			position-anchor: ${anchorName};
+			${cssForPlacement(placement)}
+			margin: 8px;
+			position-try-fallbacks:
+				flip-block,
+				flip-inline,
+				flip-block flip-inline;
+		}
+	`)
+	surface.dataset.overlayRef = opts.id
+	const existing = shadowRoot.adoptedStyleSheets
+	shadowRoot.adoptedStyleSheets = [...existing, sheet]
+
+	return () => {
+		if (priorAnchorName) {
+			anchorEl.style.setProperty('anchor-name', priorAnchorName)
+		} else {
+			anchorEl.style.removeProperty('anchor-name')
+		}
+		shadowRoot.adoptedStyleSheets = shadowRoot.adoptedStyleSheets.filter((s) => s !== sheet)
+		delete surface.dataset.overlayRef
+	}
+}
+
+function cssForPlacement(p: OverlayPlacement): string {
+	// Minimal mapping for the Tier 1 stylesheet. The browser's
+	// `position-try-fallbacks` flips when the preferred side doesn't fit,
+	// so only the starting side needs to be encoded here.
+	switch (p) {
+		case 'top':
+		case 'top-start':
+			return 'bottom: anchor(top); left: anchor(start);'
+		case 'top-end':
+			return 'bottom: anchor(top); right: anchor(end);'
+		case 'bottom':
+		case 'bottom-start':
+			return 'top: anchor(bottom); left: anchor(start);'
+		case 'bottom-end':
+			return 'top: anchor(bottom); right: anchor(end);'
+		case 'left':
+		case 'left-start':
+			return 'right: anchor(left); top: anchor(start);'
+		case 'left-end':
+			return 'right: anchor(left); bottom: anchor(end);'
+		case 'right':
+		case 'right-start':
+			return 'left: anchor(right); top: anchor(start);'
+		case 'right-end':
+			return 'left: anchor(right); bottom: anchor(end);'
+	}
+}
+
+/* ======================================================================= *
+ *                   Tier 2 — Popover API (top-layer only)                   *
+ * ======================================================================= */
+
+/**
+ * Wire the Popover API lifecycle — the surface gets `popover="auto"` and
+ * `showPopover()` is called to promote it into the native top layer. No
+ * position math here; the caller pairs this with `positionFloatingUI` for
+ * the geometry, since Tier 2 is Popover-for-stacking + Floating UI-for-math.
+ *
+ * Returns a cleanup function that hides the popover and strips the attr.
+ */
+export function positionPopoverAPI(surface: HTMLElement): () => void {
+	if (!CAPS.popover) {
+		throw new Error('positionPopoverAPI requires Popover API support')
+	}
+	surface.setAttribute('popover', 'auto')
+	try {
+		;(surface as unknown as { showPopover(): void }).showPopover()
+	} catch {
+		// showPopover can throw if already shown or detached; the component
+		// is responsible for calling this on an already-mounted, not-yet-shown
+		// surface. Silently swallowing a double-open is fine.
+	}
+	return () => {
+		try {
+			;(surface as unknown as { hidePopover?: () => void }).hidePopover?.()
+		} catch {
+			// already hidden / disconnected — fine.
+		}
+		surface.removeAttribute('popover')
+	}
+}
+
+/* ======================================================================= *
+ *                  Tier 2 / 3 — Floating UI position math                   *
+ * ======================================================================= */
+
+export interface FloatingUIOptions {
+	/** Preferred placement; Floating UI's `flip` middleware handles falls. */
+	placement?: OverlayPlacement
+	/** Padding used by `shift` + `size` middleware. Defaults to
+	 *  `ANCHOR_FIT_PADDING_PX` from overlay.layout. */
+	padding?: number
+	/** Gap between anchor and surface. Default 8px. */
+	offsetPx?: number
+	/** Whether `autoUpdate` should track element resizes. Default true. */
+	track?: boolean
+}
+
+/**
+ * Floating UI-driven positioning. Returns a cold Observable — subscribe to
+ * start positioning, unsubscribe to stop tracking (teardown cancels the
+ * `autoUpdate` loop). The caller composes with `takeUntil(this.disconnecting)`:
+ *
+ *     positionFloatingUI(surface, anchor, opts)
+ *       .pipe(takeUntil(this.disconnecting))
+ *       .subscribe()
+ *
+ * Middleware (stack, in order):
+ *   offset(opts.offsetPx)
+ *   → flip({ fallbackPlacements: [...] })
+ *   → shift({ padding: opts.padding })
+ *   → size({ apply: clamp maxWidth AND maxHeight from availableWidth/Height })
+ *
+ * `flip` is chosen over `autoPlacement` because element-anchored overlays
+ * should respect the trigger's spatial context (menus shouldn't jump
+ * sides). Dialog uses `autoPlacement` because it's point-anchored.
+ */
+export function positionFloatingUI(
+	surface: HTMLElement,
+	anchor: ResolvedAnchor,
+	opts: FloatingUIOptions = {},
+): Observable<void> {
+	return new Observable<void>((subscriber) => {
+		const reference = anchor.el ?? anchor.virtual
+		if (!reference) {
+			subscriber.error(new Error('positionFloatingUI requires an element or virtual anchor'))
+			return
+		}
+
+		const placement: Placement = (opts.placement ?? 'bottom-start') as Placement
+		const padding = opts.padding ?? ANCHOR_FIT_PADDING_PX
+		const offsetPx = opts.offsetPx ?? 8
+
+		const update = async (): Promise<void> => {
+			try {
+				const { x, y } = await computePosition(reference, surface, {
+					strategy: 'fixed',
+					placement,
+					middleware: [
+						offset(offsetPx),
+						flip({ padding, fallbackPlacements: defaultFallbacks(placement) }),
+						shift({ padding }),
+						size({
+							padding,
+							apply({ availableWidth, availableHeight, elements }) {
+								elements.floating.style.maxWidth = `${Math.max(0, availableWidth)}px`
+								elements.floating.style.maxHeight = `${Math.max(0, availableHeight)}px`
+							},
+						}),
+					],
+				})
+				Object.assign(surface.style, {
+					position: 'fixed',
+					left: `${Math.round(x)}px`,
+					top: `${Math.round(y)}px`,
+					transform: 'none',
+				})
+				subscriber.next()
+			} catch (err) {
+				subscriber.error(err)
+			}
+		}
+
+		const cleanup = autoUpdate(reference, surface, update, {
+			ancestorScroll: true,
+			ancestorResize: true,
+			elementResize: opts.track !== false,
+		})
+
+		return () => {
+			cleanup()
+		}
+	})
+}
+
+function defaultFallbacks(preferred: Placement): Placement[] {
+	// Flip to the opposite side first, then try the perpendicular ends.
+	// Small, deterministic list — not exhaustive.
+	switch (preferred) {
+		case 'bottom-start':
+			return ['top-start', 'bottom-end', 'top-end']
+		case 'bottom-end':
+			return ['top-end', 'bottom-start', 'top-start']
+		case 'top-start':
+			return ['bottom-start', 'top-end', 'bottom-end']
+		case 'top-end':
+			return ['bottom-end', 'top-start', 'bottom-start']
+		case 'left-start':
+			return ['right-start', 'left-end', 'right-end']
+		case 'left-end':
+			return ['right-end', 'left-start', 'right-start']
+		case 'right-start':
+			return ['left-start', 'right-end', 'left-end']
+		case 'right-end':
+			return ['left-end', 'right-start', 'left-start']
+		case 'top':
+			return ['bottom', 'left', 'right']
+		case 'bottom':
+			return ['top', 'left', 'right']
+		case 'left':
+			return ['right', 'top', 'bottom']
+		case 'right':
+			return ['left', 'top', 'bottom']
+		default:
+			return ['top-start', 'bottom-end']
+	}
+}