export const SETTINGS_TARGET_ATTRIBUTE = "data-settings-target"; export const SETTINGS_TARGET_FOCUS_ATTRIBUTE = "data-settings-target-focus"; export const SETTINGS_TARGET_HIGHLIGHT_ATTRIBUTE = "data-settings-target-highlight"; export const SETTINGS_TARGET_REQUEST_EVENT = "kandev:settings-target"; export type SettingsTargetRequestDetail = { targetId: string }; export type SettingsTargetRegistry = { register: (targetId: string, element: HTMLElement) => () => void; request: (targetId: string) => boolean; }; type RevealOptions = { highlightDurationMs?: number; reducedMotion?: boolean; settleDurationMs?: number; }; const DEFAULT_HIGHLIGHT_DURATION_MS = 1400; const DEFAULT_SETTLE_DURATION_MS = 2500; const highlightTimers = new WeakMap(); export function settingsTargetFromHash(hash: string): string | null { if (!hash.startsWith("#") || hash.length === 1) return null; try { return decodeURIComponent(hash.slice(1)) || null; } catch { return null; } } export function settingsTargetSelector(targetId: string): string { return `[${SETTINGS_TARGET_ATTRIBUTE}="${CSS.escape(targetId)}"]`; } export function emitSettingsTargetRequest(targetId: string): void { if (typeof window === "undefined") return; window.dispatchEvent( new CustomEvent(SETTINGS_TARGET_REQUEST_EVENT, { detail: { targetId }, }), ); } export function createSettingsTargetRegistry( reveal: (element: HTMLElement) => void = revealSettingsTarget, ): SettingsTargetRegistry { const targets = new Map(); let pendingTargetId: string | null = null; return { register(targetId, element) { targets.set(targetId, element); element.setAttribute(SETTINGS_TARGET_ATTRIBUTE, targetId); if (pendingTargetId === targetId) { pendingTargetId = null; reveal(element); } return () => { if (targets.get(targetId) === element) targets.delete(targetId); if (element.getAttribute(SETTINGS_TARGET_ATTRIBUTE) === targetId) { element.removeAttribute(SETTINGS_TARGET_ATTRIBUTE); } }; }, request(targetId) { const element = targets.get(targetId); if (!element) { pendingTargetId = targetId; return false; } pendingTargetId = null; reveal(element); return true; }, }; } export function revealSettingsTarget(element: HTMLElement, options: RevealOptions = {}): void { const reducedMotion = options.reducedMotion ?? prefersReducedMotion(); element.scrollIntoView?.({ behavior: reducedMotion ? "auto" : "smooth", block: "center", }); focusTargetWithin(element); restartTargetHighlight(element, options.highlightDurationMs ?? DEFAULT_HIGHLIGHT_DURATION_MS); keepTargetCentered(element, options.settleDurationMs ?? DEFAULT_SETTLE_DURATION_MS); } let cancelActiveSettle: (() => void) | null = null; /** * Content around the target often loads asynchronously after the initial * scroll (e.g. sections above it fetch data and grow), pushing the target out * of view. Re-center it whenever an ancestor resizes during a short settle * window, backing off as soon as the user scrolls or interacts. */ function keepTargetCentered(element: HTMLElement, durationMs: number): void { cancelActiveSettle?.(); if (typeof ResizeObserver === "undefined" || durationMs <= 0) return; const baselines = new Map(); const observer = new ResizeObserver((entries) => { let shifted = false; for (const entry of entries) { const size = `${entry.contentRect.width}x${entry.contentRect.height}`; if (baselines.has(entry.target) && baselines.get(entry.target) !== size) shifted = true; baselines.set(entry.target, size); } if (shifted && element.isConnected) { element.scrollIntoView?.({ behavior: "auto", block: "center" }); } }); for (let node: HTMLElement | null = element; node; node = node.parentElement) { observer.observe(node); } const interactionEvents = ["wheel", "touchstart", "pointerdown", "keydown"] as const; const cancel = () => { observer.disconnect(); window.clearTimeout(timer); for (const type of interactionEvents) { window.removeEventListener(type, cancel, { capture: true }); } if (cancelActiveSettle === cancel) cancelActiveSettle = null; }; for (const type of interactionEvents) { window.addEventListener(type, cancel, { capture: true, passive: true }); } const timer = window.setTimeout(cancel, durationMs); cancelActiveSettle = cancel; } function focusTargetWithin(element: HTMLElement): void { const focusTarget = element.querySelector(`[${SETTINGS_TARGET_FOCUS_ATTRIBUTE}]`) ?? element.querySelector( `input:not([disabled]), textarea:not([disabled]), select:not([disabled]), button:not([disabled]), a[href], [tabindex]:not([tabindex="-1"])`, ); const target = focusTarget ?? element; if (!focusTarget && !element.hasAttribute("tabindex")) element.tabIndex = -1; target.focus({ preventScroll: true }); } function restartTargetHighlight(element: HTMLElement, durationMs: number): void { const previousTimer = highlightTimers.get(element); if (previousTimer !== undefined) window.clearTimeout(previousTimer); element.removeAttribute(SETTINGS_TARGET_HIGHLIGHT_ATTRIBUTE); void element.offsetWidth; element.setAttribute(SETTINGS_TARGET_HIGHLIGHT_ATTRIBUTE, "true"); const timer = window.setTimeout(() => { element.removeAttribute(SETTINGS_TARGET_HIGHLIGHT_ATTRIBUTE); highlightTimers.delete(element); }, durationMs); highlightTimers.set(element, timer); } function prefersReducedMotion(): boolean { return ( typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches ); }