@mhmo91/schmancy 0.9.13 → 0.9.14

package/src/overlay/overlay.gestures.ts

@@ -0,0 +1,131 @@
+import { filter, fromEvent, merge, Observable, Subject, take, takeUntil, tap } from 'rxjs'
+
+/**
+ * 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.
+ *
+ * Thresholds are policy constants, not magic numbers.
+ */
+
+/** Distance beyond which the gesture dismisses, in px. */
+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). */
+export const DRAG_START_TOP_PX = 40
+/** Snap-back spring duration when gesture doesn't pass threshold. */
+export const SNAP_BACK_MS = 300
+
+export interface SwipeInputs {
+	/** The surface element to track gestures on. */
+	surface: HTMLElement
+	/** Optional drag handle. When provided, drag can start from anywhere on
+	 *  the handle; without it, drag must start in the top DRAG_START_TOP_PX band. */
+	dragHandle?: HTMLElement | null
+	/** Completes the gesture stream (component disconnect / layout change). */
+	until$: Observable<unknown>
+}
+
+/**
+ * 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.
+ */
+export function swipeToDismiss$(inputs: SwipeInputs): Observable<'dismiss'> {
+	const { surface, dragHandle, until$ } = inputs
+
+	return new Observable<'dismiss'>((subscriber) => {
+		const dragTarget = dragHandle ?? surface
+		const stopCurrent$ = new Subject<void>()
+
+		let dragging = false
+		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.
+			filter((e) => {
+				if (dragHandle) return true
+				const touch = e.touches[0]
+				const rect = surface.getBoundingClientRect()
+				return touch.clientY - rect.top <= DRAG_START_TOP_PX
+			}),
+			tap((e) => {
+				dragging = true
+				startY = e.touches[0].clientY
+				startTime = performance.now()
+				currentDelta = 0
+				surface.style.transition = 'none'
+				surface.style.willChange = 'transform'
+			}),
+		)
+
+		const touchMove$ = fromEvent<TouchEvent>(surface, 'touchmove', { passive: false }).pipe(
+			filter(() => dragging),
+			filter((e) => e.touches.length === 1),
+			tap((e) => {
+				const deltaY = e.touches[0].clientY - startY
+				// Rubber-band on upward drag.
+				currentDelta = deltaY < 0 ? deltaY * 0.2 : deltaY
+				surface.style.transform = `translateY(${currentDelta}px)`
+				e.preventDefault()
+			}),
+		)
+
+		const touchEnd$ = merge(
+			fromEvent<TouchEvent>(surface, 'touchend', { passive: true }),
+			fromEvent<TouchEvent>(surface, 'touchcancel', { passive: true }),
+		).pipe(
+			filter(() => dragging),
+			tap(() => {
+				dragging = false
+				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)
+
+				surface.style.willChange = ''
+
+				if (shouldDismiss) {
+					// Finish translate off-screen for visual continuity with the dismiss
+					// animation; the caller's teardown will then 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')
+					subscriber.complete()
+				} else {
+					// Snap back to 0.
+					surface.style.transition = `transform ${SNAP_BACK_MS}ms cubic-bezier(0.16, 1, 0.3, 1)`
+					surface.style.transform = 'translateY(0)'
+				}
+			}),
+		)
+
+		merge(touchStart$, touchMove$, touchEnd$)
+			.pipe(takeUntil(merge(stopCurrent$, until$)))
+			.subscribe()
+
+		return () => {
+			stopCurrent$.next()
+			stopCurrent$.complete()
+			surface.style.transition = ''
+			surface.style.transform = ''
+			surface.style.willChange = ''
+		}
+	}).pipe(take(1))
+}

package/src/overlay/overlay.layout.ts

@@ -0,0 +1,76 @@
+import type { Anchor, OverlayLayout } from './overlay.types'
+
+/**
+ * Layout dispatch engine — pure function of (anchor, content, viewport).
+ * No DOM access, no side effects — testable with synthetic inputs.
+ *
+ * Thresholds are policy constants, not magic numbers. Changes are visible
+ * as named-constant diffs, not hidden in inline literals (state skill:
+ * "thresholds ARE the policy").
+ */
+
+/** Below this viewport width, every overlay becomes a bottom sheet. */
+export const NARROW_VIEWPORT_PX = 640
+
+/** Content taller than this fraction of viewport height → sheet. */
+export const TALL_CONTENT_FRACTION = 0.8
+
+/** Content wider than this fraction of viewport width → sheet. */
+export const WIDE_CONTENT_FRACTION = 0.9
+
+/** Floating UI / CSS anchor-positioning safety padding. */
+export const ANCHOR_FIT_PADDING_PX = 16
+
+export interface LayoutInputs {
+	anchor?: Anchor
+	content: { width: number; height: number }
+	viewport: {
+		width: number
+		height: number
+		/** `matchMedia('(pointer: coarse)').matches` at call time. */
+		isCoarsePointer: boolean
+	}
+}
+
+/**
+ * Priority order:
+ *   1. viewport / content forces sheet
+ *   2. anchor provided → anchored (the novel default)
+ *   3. fallback → centered
+ *
+ * Floating UI's `flip` + `shift` + `size` middleware handles "anchor
+ * doesn't fit initially" — it returns a fitting position rather than
+ * rejecting. So step 2 does NOT branch on "does the anchor fit?";
+ * Floating UI's output IS the answer. If content is genuinely too
+ * large for any anchored position, step 1 already routed to sheet.
+ */
+export function resolveLayout(inputs: LayoutInputs): OverlayLayout {
+	const { anchor, content, viewport } = inputs
+
+	const isNarrow = viewport.width < NARROW_VIEWPORT_PX
+	const isCoarse = viewport.isCoarsePointer
+	const contentTall = content.height > viewport.height * TALL_CONTENT_FRACTION
+	const contentWide = content.width > viewport.width * WIDE_CONTENT_FRACTION
+
+	if (isNarrow || isCoarse || contentTall || contentWide) {
+		return 'sheet'
+	}
+
+	if (anchor !== undefined) {
+		return 'anchored'
+	}
+
+	return 'centered'
+}
+
+/**
+ * Read the current viewport + pointer inputs. Separated so tests can
+ * substitute synthetic inputs and the `resolveLayout` fn stays pure.
+ */
+export function readViewport(): LayoutInputs['viewport'] {
+	return {
+		width: window.innerWidth,
+		height: window.innerHeight,
+		isCoarsePointer: window.matchMedia('(pointer: coarse)').matches,
+	}
+}

package/src/overlay/overlay.service.ts

@@ -0,0 +1,299 @@
+import {
+	defer,
+	defaultIfEmpty,
+	distinctUntilChanged,
+	EMPTY,
+	firstValueFrom,
+	fromEvent,
+	map,
+	merge,
+	Observable,
+	Subject,
+	switchMap,
+	take,
+	takeUntil,
+} from 'rxjs'
+import type { THistoryStrategy } from '../area/router.types'
+import { SchmancyOverlay } from './overlay.component'
+import {
+	clearStack,
+	currentStack,
+	elementsByTag$,
+	markModal,
+	pushEntry,
+	removeEntry,
+	stack$ as internalStack$,
+	unmarkModal,
+} from './overlay.stack'
+import type {
+	CloseReason,
+	OverlayConfirmOptions,
+	Content,
+	OverlayEntry,
+	OverlayPromptOptions,
+	ShowOptions,
+} from './overlay.types'
+
+/**
+ * Public read-only stream of the current overlay stack. Subscribe to
+ * observe stack changes — e.g. to update a breadcrumb, show a "close
+ * all" button, or gate another action while any overlay is open.
+ *
+ * Emits synchronously with the current snapshot on subscribe. Never
+ * completes — the caller owns teardown via `takeUntil(this.disconnecting)`.
+ */
+export const openOverlays$: Observable<readonly OverlayEntry[]> = internalStack$
+
+/* ======================================================================= *
+ *                                   show                                    *
+ * ======================================================================= */
+
+/**
+ * Open an overlay containing `content`. Returns a cold Observable — the
+ * overlay mounts on subscribe and dismisses on unsubscribe. Emits at
+ * most one value (the result from content's `close` event) then completes.
+ *
+ * The subscription IS the overlay lifecycle. `takeUntil(this.disconnecting)`
+ * on the caller's side means the overlay auto-dismisses when the caller
+ * unmounts — no handles to track, no leaks.
+ *
+ * **Anchored is the novel default.** When triggered by a user event, pass
+ * it as `anchor` — the overlay blooms from the point of attention. Falls
+ * back to centered or sheet when the viewport / content makes that the
+ * better layout (see overlay.layout.ts).
+ *
+ * @example
+ * show(MyEditor, { props: { id }, anchor: event })
+ *   .pipe(takeUntil(this.disconnecting))
+ *   .subscribe(saved => saved && this.store.persist(saved))
+ */
+export function show<T = void>(
+	content: Content,
+	options: ShowOptions = {},
+): Observable<T | undefined> {
+	return defer(() => {
+		return new Observable<T | undefined>((subscriber) => {
+			let el: SchmancyOverlay | null = null
+			let entry: OverlayEntry | null = null
+			let historyPushed = false
+			let settled = false
+
+			const teardown$ = new Subject<void>()
+
+			const mount = async () => {
+				try {
+					// Create and append the overlay element.
+					el = document.createElement('schmancy-overlay') as SchmancyOverlay
+					;(document.body ?? document.documentElement).appendChild(el)
+					await el.updateComplete
+
+					// Open it — mount content, resolve layout, animate in.
+					await el.open(content, options)
+
+					// Register with the stack (post-open so layout is resolved).
+					const id = generateId()
+					entry = {
+						id,
+						element: el,
+						layout: el.layout,
+					}
+					pushEntry(entry)
+
+					// Register modality for the stack-aware inert manager when modal.
+					if (el.modal && el.parentElement) {
+						markModal(id, el)
+					}
+
+					// History integration — push a sentinel unless silent.
+					const strategy: THistoryStrategy = options.historyStrategy ?? 'push'
+					if (strategy === 'push') {
+						history.pushState({ __schmancyOverlayId: id }, '', location.href)
+						historyPushed = true
+					} else if (strategy === 'replace') {
+						history.replaceState({ __schmancyOverlayId: id }, '', location.href)
+					}
+
+					// popstate — close this overlay when the user hits back past us.
+					// If another overlay's popstate fires first, that's fine; each overlay
+					// handles its own via this listener.
+					if (historyPushed) {
+						fromEvent<PopStateEvent>(window, 'popstate')
+							.pipe(take(1), takeUntil(teardown$))
+							.subscribe(() => {
+								// Avoid double-pop on teardown — set settled so the
+								// teardown fn doesn't call history.back() again.
+								settled = true
+								void el?.close('popstate')
+							})
+					}
+
+					// Subscribe to the element's internal close$ — the single source of
+					// truth for lifecycle completion. Emits reason + optional result.
+					el.closed$.pipe(take(1), takeUntil(teardown$)).subscribe(({ result }) => {
+						settled = true
+						subscriber.next(result as T | undefined)
+						subscriber.complete()
+					})
+				} catch (err) {
+					subscriber.error(err)
+				}
+			}
+
+			void mount()
+
+			return () => {
+				teardown$.next()
+				teardown$.complete()
+
+				// Unsubscribe path — caller cancelled. Tear down the overlay.
+				if (el && !settled) {
+					void el.close('programmatic')
+				}
+
+				// Clean up registry entries.
+				if (entry) {
+					unmarkModal(entry.id)
+					removeEntry(entry.id)
+				}
+
+				// Pop history if we pushed one and it's still current.
+				if (historyPushed && !settled) {
+					// Check before calling — if the user already popped, this is a noop.
+					if (history.state?.__schmancyOverlayId === entry?.id) {
+						history.back()
+					}
+					historyPushed = false
+				}
+
+				// Remove element after exit animation has had a chance to play.
+				queueMicrotask(() => {
+					el?.remove()
+					el = null
+				})
+			}
+		})
+	})
+}
+
+/* ======================================================================= *
+ *                            confirm / prompt sugar                         *
+ * ======================================================================= */
+
+/**
+ * Yes/no confirmation dialog. Returns a Promise that resolves with the
+ * user's choice. `variant: 'danger'` flips to destructive styling and
+ * `role="alertdialog"`.
+ */
+export async function confirm(options: OverlayConfirmOptions = {}): Promise<boolean> {
+	// Lazy-import the confirm body so push-only callers don't ship these
+	// deps. The module is small; one-shot import penalty is fine.
+	const { SchmancyOverlayPromptBody } = await import('./overlay.confirm-body')
+
+	const result = await firstValueFrom(
+		show<boolean>(SchmancyOverlayPromptBody, {
+			anchor: options.anchor,
+			signal: options.signal,
+			props: {
+				mode: 'confirm',
+				heading: options.title,
+				subtitle: options.subtitle,
+				message: options.message,
+				confirmText: options.confirmText ?? 'Confirm',
+				cancelText: options.cancelText ?? 'Cancel',
+				variant: options.variant ?? 'default',
+			},
+		}).pipe(defaultIfEmpty(false as boolean | undefined)),
+	)
+	return result === true
+}
+
+/**
+ * Input prompt dialog. Returns the entered string, or `null` if the user
+ * cancels or dismisses.
+ */
+export async function prompt(options: OverlayPromptOptions = {}): Promise<string | null> {
+	const { SchmancyOverlayPromptBody } = await import('./overlay.confirm-body')
+
+	const result = await firstValueFrom(
+		show<string | null>(SchmancyOverlayPromptBody, {
+			anchor: options.anchor,
+			signal: options.signal,
+			props: {
+				mode: 'prompt',
+				heading: options.title,
+				subtitle: options.subtitle,
+				message: options.message,
+				label: options.label,
+				defaultValue: options.defaultValue ?? '',
+				placeholder: options.placeholder,
+				inputType: options.inputType ?? 'text',
+				pattern: options.pattern,
+				required: options.required ?? false,
+				confirmText: options.confirmText ?? 'OK',
+				cancelText: options.cancelText ?? 'Cancel',
+			},
+		}).pipe(defaultIfEmpty(null as string | null | undefined)),
+	)
+	return typeof result === 'string' ? result : null
+}
+
+/* ======================================================================= *
+ *                              overlayEvents                                *
+ * ======================================================================= */
+
+/**
+ * Subscribe to custom events emitted from any currently-open overlay
+ * whose content matches `tagName`. Inspired by `area.on(name)` — keyed
+ * by tag name (stable across HMR / lazy chunks) rather than a uid or
+ * class reference.
+ *
+ * The returned Observable never completes on its own — the caller owns
+ * teardown via `takeUntil(this.disconnecting)`. During gaps where no
+ * matching overlay is open, no events are emitted; when an instance
+ * mounts, events flow.
+ *
+ * Stacked instances of the same content merge their event streams.
+ */
+export function overlayEvents<E extends Event = CustomEvent>(
+	tagName: string,
+	eventName: string,
+): Observable<E> {
+	return elementsByTag$(tagName).pipe(
+		distinctUntilChanged((a, b) => a.length === b.length && a.every((el, i) => el === b[i])),
+		switchMap((elements) =>
+			elements.length === 0 ? EMPTY : merge(...elements.map((el) => fromEvent<E>(el, eventName))),
+		),
+		map((e) => e),
+	)
+}
+
+/* ======================================================================= *
+ *                                dismissAll                                 *
+ * ======================================================================= */
+
+/**
+ * Close every currently-open overlay. LIFO order. Imperative — use for
+ * app-level flows like logout or route reset.
+ */
+export function dismissAll(): void {
+	const stack = [...currentStack()]
+	// LIFO: close top-of-stack first.
+	for (let i = stack.length - 1; i >= 0; i--) {
+		const entry = stack[i]
+		const overlay = entry.element as SchmancyOverlay
+		void overlay.close('programmatic')
+	}
+	clearStack()
+}
+
+/* ======================================================================= *
+ *                                 helpers                                   *
+ * ======================================================================= */
+
+function generateId(): string {
+	// 8-char base36 is enough entropy for session-scoped uniqueness.
+	return 'ov_' + Math.random().toString(36).slice(2, 10) + Date.now().toString(36)
+}
+
+// Re-export the close reason type for consumers who want to narrow on it.
+export type { CloseReason }

package/src/overlay/overlay.stack.ts

@@ -0,0 +1,171 @@
+import { BehaviorSubject, distinctUntilChanged, map, Observable } from 'rxjs'
+import type { OverlayEntry } from './overlay.types'
+
+/**
+ * Overlay stack — single source of truth for "what is currently open."
+ *
+ * A module-scope BehaviorSubject matching the `schmancy` skill's
+ * "contexts at module scope; many small contexts beat one monolith"
+ * guidance. Reactive pipelines inside the overlay service and public
+ * `openOverlays$` observable project off this.
+ *
+ * Scroll lock and the stack-aware inert manager are both derived from
+ * the stack state — no separate mutable counter variables. Honors rxjs
+ * SUBSCRIPTION_IS_STATE: the stack IS the state; scroll lock / inert
+ * are declarative projections.
+ */
+
+const stack$$ = new BehaviorSubject<readonly OverlayEntry[]>([])
+
+/** Public read-only stream of the current stack. Emits on every push/pop. */
+export const stack$: Observable<readonly OverlayEntry[]> = stack$$.asObservable()
+
+/** Synchronous snapshot. Use only when a component can't subscribe. */
+export function currentStack(): readonly OverlayEntry[] {
+	return stack$$.value
+}
+
+/** Append an entry (top of stack). */
+export function pushEntry(entry: OverlayEntry): void {
+	stack$$.next([...stack$$.value, entry])
+}
+
+/** Remove by id. No-op if the id is not in the stack. */
+export function removeEntry(id: string): void {
+	const current = stack$$.value
+	const next = current.filter((e) => e.id !== id)
+	if (next.length !== current.length) {
+		stack$$.next(next)
+	}
+}
+
+/** Clear the entire stack. Used by dismissAll(). */
+export function clearStack(): void {
+	if (stack$$.value.length > 0) {
+		stack$$.next([])
+	}
+}
+
+/** Top entry (LIFO). Undefined when stack is empty. */
+export function topEntry(): OverlayEntry | undefined {
+	const s = stack$$.value
+	return s[s.length - 1]
+}
+
+/* ---------------- scroll lock -------------------------------------------- */
+
+/**
+ * Ref-counted body scroll lock, derived from the stack's length.
+ * Subscription is idempotent — subscribing multiple times won't stack
+ * effects, because it's a distinctUntilChanged boolean projection.
+ *
+ * Inner overlay close does NOT release the lock while an outer is still
+ * open (this was the pre-existing bug in sheet.service.ts).
+ */
+let scrollLockActive = false
+let previousOverflow = ''
+let previousScrollbarGutter = ''
+
+stack$$
+	.pipe(
+		map((s) => s.length > 0),
+		distinctUntilChanged(),
+	)
+	.subscribe((shouldLock) => {
+		if (typeof document === 'undefined') return
+
+		if (shouldLock && !scrollLockActive) {
+			previousOverflow = document.documentElement.style.overflow
+			previousScrollbarGutter = document.documentElement.style.getPropertyValue('scrollbar-gutter')
+			document.documentElement.style.overflow = 'hidden'
+			document.documentElement.style.setProperty('scrollbar-gutter', 'stable')
+			scrollLockActive = true
+		} else if (!shouldLock && scrollLockActive) {
+			document.documentElement.style.overflow = previousOverflow
+			if (previousScrollbarGutter) {
+				document.documentElement.style.setProperty('scrollbar-gutter', previousScrollbarGutter)
+			} else {
+				document.documentElement.style.removeProperty('scrollbar-gutter')
+			}
+			previousOverflow = ''
+			previousScrollbarGutter = ''
+			scrollLockActive = false
+		}
+	})
+
+/* ---------------- stack-aware inert -------------------------------------- */
+
+/**
+ * When the first modal overlay opens, mark every sibling outside the
+ * overlay host subtree as `inert` so AT and keyboard focus can't reach
+ * them. Restored when the last modal overlay closes.
+ *
+ * Note: native `<dialog>.showModal()` already inerts the rest of the
+ * document automatically. We keep this as a safety net for:
+ *   - anchored (popover) overlays which are non-modal by design but may
+ *     carry `modal: true` as the escape hatch;
+ *   - stacked overlays where an inner modal opens above a non-modal —
+ *     the sibling-inert is a no-op but we still guarantee the invariant.
+ *
+ * Callers that don't want inert (anchored/menu overlays) skip registration
+ * via `markNonModal(id)`.
+ */
+const modalIds = new Set<string>()
+const inertedSiblings = new Set<HTMLElement>()
+
+export function markModal(id: string, hostContainer: HTMLElement): void {
+	modalIds.add(id)
+	if (modalIds.size === 1) {
+		applyInert(hostContainer)
+	}
+}
+
+export function unmarkModal(id: string): void {
+	modalIds.delete(id)
+	if (modalIds.size === 0) {
+		releaseInert()
+	}
+}
+
+function applyInert(hostContainer: HTMLElement): void {
+	const parent = hostContainer.parentElement ?? document.body
+	for (let i = 0; i < parent.children.length; i++) {
+		const child = parent.children[i]
+		if (child !== hostContainer && child instanceof HTMLElement && !child.inert) {
+			child.inert = true
+			inertedSiblings.add(child)
+		}
+	}
+}
+
+function releaseInert(): void {
+	for (const el of inertedSiblings) {
+		el.inert = false
+	}
+	inertedSiblings.clear()
+}
+
+/* ---------------- overlayEvents multicast helper ------------------------- */
+
+/**
+ * Returns an Observable of `tagName` elements currently in the stack.
+ * The overlayEvents public helper composes `fromEvent` over this stream
+ * via switchMap to tap events without owning the overlay lifecycle.
+ *
+ * Stays alive across open/close cycles — the caller owns completion via
+ * `takeUntil(this.disconnecting)`, matching the house rxjs convention.
+ */
+export function elementsByTag$(tagName: string): Observable<readonly HTMLElement[]> {
+	const lower = tagName.toLowerCase()
+	return stack$$.pipe(
+		map((entries) => {
+			const matches: HTMLElement[] = []
+			for (const entry of entries) {
+				const inner = entry.element.querySelector<HTMLElement>(lower)
+				if (inner) matches.push(inner)
+			}
+			return matches
+		}),
+		distinctUntilChanged((a, b) => a.length === b.length && a.every((el, i) => el === b[i])),
+	)
+}