@mhmo91/schmancy 0.9.13 → 0.9.14

package/skills/schmancy/overlay.md

@@ -0,0 +1,200 @@
+# Overlay — `show` / `<schmancy-overlay>`
+
+> One overlay primitive. Anchored by default. Observable lifecycle. Replaces `sheet` + `$dialog`.
+
+## Import
+
+```ts
+import {
+  show, confirm, prompt,
+  openOverlays$, overlayEvents,
+  dismissAll, lazy,
+} from '@mhmo91/schmancy/overlay'
+```
+
+## The novel default — anchored
+
+When you're triggering an overlay from a user gesture (click, touch), pass the event as `anchor`. The overlay blooms from the point of attention instead of materializing at the viewport center.
+
+```ts
+private handlePick = (ev: MouseEvent) => {
+  show(TemplatePicker, { anchor: ev, props: { kind: 'email' } })
+    .pipe(takeUntil(this.disconnecting))
+    .subscribe(picked => { if (picked) this.template = picked })
+}
+```
+
+Centered is the fallback (no anchor given). Sheet is the responsive adaptation (narrow viewport / touch / oversized content). You never pick layout — the system does.
+
+## API
+
+| Export | Signature | Purpose |
+|---|---|---|
+| `show<T>(content, opts?)` | `Observable<T \| undefined>` | Primary verb. Cold stream — subscribe to mount, unsubscribe to dismiss. |
+| `confirm(opts)` | `Promise<boolean>` | Yes/no dialog. `variant: 'danger'` for destructive. |
+| `prompt(opts)` | `Promise<string \| null>` | Single-line input. |
+| `dismissAll()` | `void` | Close every open overlay (LIFO). |
+| `openOverlays$` | `Observable<readonly OverlayEntry[]>` | Mechanical state — the current stack. |
+| `overlayEvents<E>(tag, evt)` | `Observable<E>` | Third-party subscription to events from any overlay of `tag`. |
+| `lazy(loader)` | `LazyComponent` | Re-exported from area for lazy-loaded content. |
+
+## Subscription IS the overlay lifecycle
+
+Inside any `$LitElement`, pipe `takeUntil(this.disconnecting)`. When the caller unmounts, the overlay auto-dismisses — no handles to track, no leaks.
+
+```ts
+show(MyForm, { props: { id }, anchor: ev })
+  .pipe(takeUntil(this.disconnecting))
+  .subscribe(saved => saved && this.store.persist(saved))
+```
+
+Programmatic dismiss = unsubscribe. Either store the Subscription and call `.unsubscribe()`, or compose a terminator stream via `takeUntil(merge(this.disconnecting, saveTrigger$))`.
+
+## How content returns a result — three platform paths
+
+Priority order:
+
+1. **CustomEvent('close', { detail })** — dispatched from content. `detail` becomes the Observable emission.
+2. **`<form method="dialog">`** — native submit. The dialog's `returnValue` is emitted.
+3. **User dismissal** — Esc / backdrop click / swipe / back-button / `.unsubscribe()` / `dismissAll()` emits `undefined`.
+
+```ts
+// Inside a content component:
+this.dispatchEvent(new CustomEvent('close', {
+  detail: savedRecord,
+  bubbles: true,
+  composed: true,   // cross shadow-DOM
+}))
+```
+
+```ts
+// Inline template with native form — zero JS
+show<string>(html`
+  <form method="dialog">
+    <button value="save">Save</button>
+    <button value="discard">Discard</button>
+    <button value="">Cancel</button>
+  </form>
+`)
+```
+
+## Options
+
+```ts
+interface ShowOptions {
+  props?: Record<string, unknown>                    // merged into component
+  anchor?: MouseEvent | HTMLElement | { x, y }       // NOVEL DEFAULT
+  dismissable?: boolean                              // default true
+  persist?: boolean                                  // reuse DOM on re-show
+  signal?: AbortSignal                               // standard cancellation
+  modal?: boolean                                    // force focus trap; rare
+  historyStrategy?: 'push' | 'replace' | 'silent'    // default 'push'
+}
+```
+
+## History integration
+
+Each `show()` pushes a history sentinel unless `historyStrategy: 'silent'`. Browser back dismisses the overlay instead of navigating the page. For forward-restore on routed callers, pair with `area.on(name)` — your overlay sits inside a route-observer's `switchMap`, so forward-navigation re-subscribes and re-opens the overlay naturally.
+
+```ts
+area.on('root').pipe(
+  map(route => route.params?.editId),
+  distinctUntilChanged(),
+  switchMap(id => id ? show(TaskEditor, { props: { id } }) : EMPTY),
+  takeUntil(this.disconnecting),
+).subscribe()
+```
+
+## Layout dispatch — internal
+
+Pure function of (anchor, content size, viewport):
+
+- Narrow viewport (< 640px) or coarse-pointer → **sheet**
+- Content > 80% viewport height or 90% width → **sheet**
+- Anchor provided → **anchored**
+- Fallback → **centered**
+
+Callers never override. The `modal: true` escape hatch forces focus trap on an anchored overlay for the rare "menu-with-destructive-item" case.
+
+## Examples
+
+### 1. Confirm / prompt / danger
+
+```ts
+if (await confirm({ title: 'Delete?', message: '...', variant: 'danger', anchor: ev })) {
+  await store.delete(id)
+}
+const name = await prompt({ label: 'Name', defaultValue: 'Untitled', anchor: ev })
+```
+
+### 2. Cancellable via AbortSignal
+
+```ts
+const ac = new AbortController()
+this.routeChange$.pipe(take(1)).subscribe(() => ac.abort())
+show(LoadingOverlay, { signal: ac.signal })
+  .pipe(takeUntil(this.disconnecting))
+  .subscribe()
+```
+
+### 3. Observe events from any open overlay without owning it
+
+```ts
+// A header progress bar reflects any upload overlay's progress.
+overlayEvents<CustomEvent<{ pct: number }>>('image-upload', 'progress')
+  .pipe(map(e => e.detail.pct), takeUntil(this.disconnecting))
+  .subscribe(pct => this.progress = pct)
+```
+
+### 4. Stack-driven UI
+
+```ts
+openOverlays$.pipe(
+  map(s => s.length > 1),
+  distinctUntilChanged(),
+  takeUntil(this.disconnecting),
+).subscribe(many => this.showCloseAllButton = many)
+```
+
+### 5. Lazy-loaded heavy overlay with error recovery
+
+```ts
+show(lazy(() => import('./canvas-editor')))
+  .pipe(
+    catchError(err => { $notify.error('Load failed'); return EMPTY }),
+    takeUntil(this.disconnecting),
+  )
+  .subscribe()
+```
+
+### 6. Non-component caller (service / test)
+
+```ts
+const saved = await firstValueFrom(
+  show<Record>(MyPicker).pipe(defaultIfEmpty(undefined))
+)
+```
+
+## Migration cheatsheet — from `sheet` / `$dialog`
+
+```
+sheet.push({ component, props })               → show(C, { props }).pipe(takeUntil(...)).subscribe()
+sheet.push({ ..., position: 'side'|'bottom' }) → show(C, { props })          // engine decides
+sheet.dismiss(uid)                             → sub.unsubscribe() | dismissAll()
+sheet.isOpen(uid)                              → openOverlays$.pipe(map(s => s.some(...)))
+
+$dialog.confirm(opts)                          → confirm(opts)
+$dialog.ask(msg, ev)                           → confirm({ message: msg, anchor: ev })
+$dialog.danger(opts)                           → confirm({ ...opts, variant: 'danger' })
+$dialog.prompt(opts)                           → prompt(opts)
+$dialog.component(tpl, { position: ev })       → show(tpl, { anchor: ev })
+$dialog.dismiss()                              → dismissAll()
+```
+
+## Principles (why this shape)
+
+- **rxjs SUBSCRIPTION_IS_STATE.** The overlay lifecycle is a subscription — setup on subscribe, teardown on unsubscribe. No imperative handles.
+- **Fewer APIs, smarter system.** Caller declares intent (`show(X, { anchor })`); the system decides layout, focus trap, positioning, scroll lock, inert, back-button handling.
+- **Native platform first.** `<dialog>` + `::backdrop` + `returnValue` carry the weight. `CustomEvent('close', { detail })` is the typed overlay on top.
+- **Anchored is novel default.** Overlays bloom from the user's gesture instead of center-of-viewport.
+- **Content identity is the key.** `overlayEvents` keys on tag name (stable across HMR). No uid strings in the public API.

package/src/overlay/index.ts

@@ -0,0 +1,15 @@
+export * from './overlay.component'
+export * from './overlay.confirm-body'
+export * from './overlay.service'
+export type {
+	Anchor,
+	CloseReason,
+	Content,
+	OverlayConfirmOptions,
+	OverlayEntry,
+	OverlayLayout,
+	OverlayPromptOptions,
+	ShowFn,
+	ShowOptions,
+} from './overlay.types'
+export { lazy } from '../area/lazy'

package/src/overlay/overlay.animations.ts

@@ -0,0 +1,137 @@
+import {
+	DURATION_BACKDROP,
+	DURATION_EXIT,
+	EASE_IN,
+	EASE_OUT,
+	prefersReducedMotion,
+	SPRING_GENTLE,
+	SPRING_SNAPPY,
+} from '../utils/animation'
+import type { OverlayLayout } from './overlay.types'
+
+/**
+ * WAAPI keyframes + options per layout + direction.
+ *
+ * One animation vocabulary — no per-element bespoke keyframes. Aligns
+ * with the `animation` skill (spring physics presets). Honors
+ * `prefers-reduced-motion` by collapsing transforms to opacity-only.
+ *
+ * Returns `null` when reduced-motion is active and only opacity change
+ * is needed — the caller sets style directly.
+ */
+
+/**
+ * Shape matches both DOM `AnimationEffectTiming` and
+ * `KeyframeAnimationOptions` so it passes structural checks in both
+ * older and newer `lib.dom.d.ts` vintages.
+ */
+export interface AnimationSpec {
+	keyframes: Keyframe[]
+	options: {
+		duration: number
+		easing: string
+		fill?: FillMode
+	}
+}
+
+export function backdropAnimation(direction: 'in' | 'out'): AnimationSpec {
+	return direction === 'in'
+		? {
+				keyframes: [{ opacity: 0 }, { opacity: 1 }],
+				options: { duration: DURATION_BACKDROP, easing: EASE_OUT, fill: 'forwards' },
+			}
+		: {
+				keyframes: [{ opacity: 1 }, { opacity: 0 }],
+				options: { duration: DURATION_BACKDROP, easing: EASE_OUT, fill: 'forwards' },
+			}
+}
+
+export function surfaceAnimation(layout: OverlayLayout, direction: 'in' | 'out'): AnimationSpec {
+	const reduced = prefersReducedMotion()
+
+	if (reduced) {
+		// Opacity-only; explicit reset to { opacity: 1, transform: none } on `in`
+		// so any leftover transform from a prior `out` doesn't persist.
+		return direction === 'in'
+			? {
+					keyframes: [
+						{ opacity: 0, transform: 'none' },
+						{ opacity: 1, transform: 'none' },
+					],
+					options: { duration: 1, easing: 'linear', fill: 'forwards' },
+				}
+			: {
+					keyframes: [
+						{ opacity: 1, transform: 'none' },
+						{ opacity: 0, transform: 'none' },
+					],
+					options: { duration: 1, easing: 'linear', fill: 'forwards' },
+				}
+	}
+
+	switch (layout) {
+		case 'centered':
+			return direction === 'in'
+				? {
+						keyframes: [
+							{ opacity: 0, transform: 'scale(0.92) translateY(16px)' },
+							{ opacity: 1, transform: 'scale(1) translateY(0)' },
+						],
+						options: {
+							duration: SPRING_SNAPPY.duration,
+							easing: SPRING_SNAPPY.easingFallback,
+							fill: 'forwards',
+						},
+					}
+				: {
+						keyframes: [
+							{ opacity: 1, transform: 'scale(1) translateY(0)' },
+							{ opacity: 0, transform: 'scale(0.96) translateY(8px)' },
+						],
+						options: { duration: DURATION_EXIT, easing: EASE_IN, fill: 'forwards' },
+					}
+
+		case 'sheet':
+			return direction === 'in'
+				? {
+						keyframes: [
+							{ opacity: 0, transform: 'translateY(100%)' },
+							{ opacity: 1, transform: 'translateY(0)' },
+						],
+						options: {
+							duration: SPRING_GENTLE.duration,
+							easing: SPRING_GENTLE.easingFallback,
+							fill: 'forwards',
+						},
+					}
+				: {
+						keyframes: [
+							{ opacity: 1, transform: 'translateY(0)' },
+							{ opacity: 0, transform: 'translateY(100%)' },
+						],
+						options: {
+							duration: DURATION_EXIT,
+							easing: EASE_IN,
+							fill: 'forwards',
+						},
+					}
+
+		case 'anchored':
+			// No transform — CSS Anchor Positioning / Floating UI owns position.
+			// Scale-from-origin via transform-origin would be nicer but conflicts
+			// with popover top-layer + position. Keep opacity-only for safety.
+			return direction === 'in'
+				? {
+						keyframes: [{ opacity: 0 }, { opacity: 1 }],
+						options: {
+							duration: SPRING_SNAPPY.duration,
+							easing: SPRING_SNAPPY.easingFallback,
+							fill: 'forwards',
+						},
+					}
+				: {
+						keyframes: [{ opacity: 1 }, { opacity: 0 }],
+						options: { duration: DURATION_EXIT, easing: EASE_IN, fill: 'forwards' },
+					}
+	}
+}