@spicetify/kit 0.1.0 → 0.2.0

package/vendor/stdlib/lib/floating.tsx

@@ -0,0 +1,298 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { React, ReactDOM } from "../src/expose/React.ts";
+import { calculateFloatingPosition } from "./floating-position.ts";
+
+const TOOLTIP_HIDE_DELAY_MS = 300;
+const FOCUSABLE_SELECTOR =
+	'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+type FloatingRole = "dialog" | "menu";
+type TriggerProps = React.AriaAttributes & {
+	disabled?: boolean;
+	onClick?: React.MouseEventHandler<HTMLElement>;
+};
+
+function useFloatingPlacement(
+	open: boolean,
+	anchorRef: React.RefObject<HTMLElement | null>,
+	surfaceRef: React.RefObject<HTMLElement | null>,
+	align: "center" | "start",
+	gap: number,
+): void {
+	React.useLayoutEffect(() => {
+		if (!open) return;
+		const anchor = anchorRef.current;
+		const surface = surfaceRef.current;
+		if (!anchor || !surface) return;
+
+		const place = () => {
+			if (!anchor.isConnected || !surface.isConnected) return;
+			const anchorRect = anchor.getBoundingClientRect();
+			const surfaceRect = surface.getBoundingClientRect();
+			const position = calculateFloatingPosition(
+				anchorRect,
+				surfaceRect,
+				{ width: window.innerWidth, height: window.innerHeight },
+				{ align, gap },
+			);
+			surface.style.left = `${position.left}px`;
+			surface.style.top = `${position.top}px`;
+			surface.style.visibility = "visible";
+			surface.dataset.placement = position.placement;
+		};
+
+		place();
+		window.addEventListener("resize", place);
+		document.addEventListener("scroll", place, true);
+		const observer = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(place);
+		observer?.observe(anchor);
+		observer?.observe(surface);
+		return () => {
+			window.removeEventListener("resize", place);
+			document.removeEventListener("scroll", place, true);
+			observer?.disconnect();
+		};
+	}, [align, anchorRef, gap, open, surfaceRef]);
+}
+
+function focusTrigger(anchor: HTMLElement | null): void {
+	anchor?.querySelector<HTMLElement>(FOCUSABLE_SELECTOR)?.focus();
+}
+
+function moveMenuFocus(event: React.KeyboardEvent<HTMLElement>): void {
+	if (!["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) return;
+	const items = [...event.currentTarget.querySelectorAll<HTMLElement>('[role^="menuitem"]:not([disabled])')];
+	if (!items.length) return;
+	event.preventDefault();
+	const currentIndex = items.indexOf(document.activeElement as HTMLElement);
+	const nextIndex =
+		event.key === "Home"
+			? 0
+			: event.key === "End"
+				? items.length - 1
+				: (currentIndex + (event.key === "ArrowDown" ? 1 : -1) + items.length) % items.length;
+	items[nextIndex]?.focus();
+}
+
+function usePopoverDismissal(
+	open: boolean,
+	close: () => void,
+	anchorRef: React.RefObject<HTMLElement | null>,
+	surfaceRef: React.RefObject<HTMLElement | null>,
+): void {
+	React.useEffect(() => {
+		if (!open) return;
+		const onDocumentMouseDown = (event: MouseEvent) => {
+			const target = event.target as Node;
+			if (!anchorRef.current?.contains(target) && !surfaceRef.current?.contains(target)) close();
+		};
+		const onDocumentKeyDown = (event: KeyboardEvent) => {
+			if (event.key !== "Escape") return;
+			event.preventDefault();
+			event.stopPropagation();
+			close();
+			requestAnimationFrame(() => focusTrigger(anchorRef.current));
+		};
+		const onDocumentFocus = (event: FocusEvent) => {
+			const target = event.target as Node;
+			if (!anchorRef.current?.contains(target) && !surfaceRef.current?.contains(target)) close();
+		};
+
+		document.addEventListener("mousedown", onDocumentMouseDown, true);
+		document.addEventListener("keydown", onDocumentKeyDown, true);
+		document.addEventListener("focusin", onDocumentFocus, true);
+		return () => {
+			document.removeEventListener("mousedown", onDocumentMouseDown, true);
+			document.removeEventListener("keydown", onDocumentKeyDown, true);
+			document.removeEventListener("focusin", onDocumentFocus, true);
+		};
+	}, [anchorRef, close, open, surfaceRef]);
+}
+
+export const Tooltip: React.FC<{
+	label: React.ReactNode;
+	children: React.ReactElement<TriggerProps>;
+}> = (props) => {
+	const id = React.useId();
+	const anchorRef = React.useRef<HTMLSpanElement>(null);
+	const tooltipRef = React.useRef<HTMLDivElement>(null);
+	const hideTimer = React.useRef<number>();
+	const [visible, setVisible] = React.useState(false);
+	const cancelHide = React.useCallback(() => window.clearTimeout(hideTimer.current), []);
+	const show = React.useCallback(() => {
+		cancelHide();
+		setVisible(true);
+	}, [cancelHide]);
+	const dismiss = React.useCallback(() => {
+		cancelHide();
+		setVisible(false);
+	}, [cancelHide]);
+	const scheduleHide = React.useCallback(() => {
+		cancelHide();
+		hideTimer.current = window.setTimeout(() => setVisible(false), TOOLTIP_HIDE_DELAY_MS);
+	}, [cancelHide]);
+	useFloatingPlacement(visible, anchorRef, tooltipRef, "center", 8);
+
+	React.useEffect(() => () => cancelHide(), [cancelHide]);
+	React.useEffect(() => {
+		if (!visible) return;
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key !== "Escape") return;
+			event.preventDefault();
+			event.stopPropagation();
+			cancelHide();
+			setVisible(false);
+		};
+		document.addEventListener("keydown", onKeyDown, true);
+		return () => document.removeEventListener("keydown", onKeyDown, true);
+	}, [cancelHide, visible]);
+
+	const existingDescription = props.children.props["aria-describedby"];
+	const describedBy = [existingDescription, id].filter(Boolean).join(" ");
+	const child = React.cloneElement(props.children, { "aria-describedby": describedBy });
+	const disabled = props.children.props.disabled === true;
+
+	return (
+		<span
+			ref={anchorRef}
+			className="spicetify-floating-anchor"
+			tabIndex={disabled ? 0 : undefined}
+			aria-describedby={disabled ? id : undefined}
+			onClickCapture={dismiss}
+			onPointerEnter={show}
+			onPointerLeave={scheduleHide}
+			onFocusCapture={show}
+			onBlurCapture={scheduleHide}
+		>
+			{child}
+			{visible
+				? ReactDOM.createPortal(
+						<div
+							ref={tooltipRef}
+							id={id}
+							role="tooltip"
+							className="spicetify-tooltip"
+							style={{ visibility: "hidden" }}
+							onPointerEnter={cancelHide}
+							onPointerLeave={scheduleHide}
+						>
+							{props.label}
+						</div>,
+						document.body,
+					)
+				: null}
+		</span>
+	);
+};
+
+export const Popover: React.FC<{
+	ariaLabel: string;
+	children: React.ReactElement<TriggerProps>;
+	content: React.ReactNode | ((close: () => void) => React.ReactNode);
+	role?: FloatingRole;
+	align?: "center" | "start";
+	className?: string;
+	tooltip?: React.ReactNode;
+	onClose?: () => void;
+}> = (props) => {
+	const id = React.useId();
+	const anchorRef = React.useRef<HTMLSpanElement>(null);
+	const surfaceRef = React.useRef<HTMLDivElement>(null);
+	const openRef = React.useRef(false);
+	const [open, setOpen] = React.useState(false);
+	const close = React.useCallback(() => {
+		if (!openRef.current) return;
+		openRef.current = false;
+		setOpen(false);
+		props.onClose?.();
+	}, [props.onClose]);
+	const toggle = () => {
+		if (openRef.current) {
+			close();
+			return;
+		}
+		openRef.current = true;
+		setOpen(true);
+	};
+	const role = props.role ?? "dialog";
+	useFloatingPlacement(open, anchorRef, surfaceRef, props.align ?? "start", 8);
+	usePopoverDismissal(open, close, anchorRef, surfaceRef);
+	React.useEffect(() => {
+		if (!open) return;
+		const frame = requestAnimationFrame(() => {
+			const surface = surfaceRef.current;
+			(surface?.querySelector<HTMLElement>(FOCUSABLE_SELECTOR) ?? surface)?.focus();
+		});
+		return () => cancelAnimationFrame(frame);
+	}, [open]);
+	React.useEffect(
+		() => () => {
+			openRef.current = false;
+		},
+		[],
+	);
+
+	const originalClick = props.children.props.onClick;
+	const trigger = React.cloneElement(props.children, {
+		"aria-haspopup": role,
+		"aria-expanded": open,
+		"aria-controls": open ? id : undefined,
+		onClick: (event: React.MouseEvent<HTMLElement>) => {
+			originalClick?.(event);
+			if (!event.defaultPrevented) toggle();
+		},
+	});
+	const describedTrigger = props.tooltip ? <Tooltip label={props.tooltip}>{trigger}</Tooltip> : trigger;
+	const surfaceClass = props.className
+		? `spicetify-popover spicetify-popover--owned ${props.className}`
+		: "spicetify-popover spicetify-popover--owned";
+
+	return (
+		<span ref={anchorRef} className="spicetify-floating-anchor">
+			{describedTrigger}
+			{open
+				? ReactDOM.createPortal(
+						<div
+							ref={surfaceRef}
+							id={id}
+							role={role}
+							aria-label={props.ariaLabel}
+							className={surfaceClass}
+							tabIndex={-1}
+							style={{ visibility: "hidden" }}
+							onKeyDown={role === "menu" ? moveMenuFocus : undefined}
+						>
+							{typeof props.content === "function" ? props.content(close) : props.content}
+						</div>,
+						document.body,
+					)
+				: null}
+		</span>
+	);
+};
+
+export const PopoverMenu: React.FC<{ children: React.ReactNode }> = (props) => (
+	<div className="spicetify-popover-menu">{props.children}</div>
+);
+
+export const PopoverMenuItem: React.FC<{
+	selected?: boolean;
+	disabled?: boolean;
+	onSelect: () => void;
+	children: React.ReactNode;
+}> = (props) => (
+	<button
+		type="button"
+		role={props.selected === undefined ? "menuitem" : "menuitemradio"}
+		aria-checked={props.selected}
+		className="spicetify-popover-menu-item"
+		disabled={props.disabled}
+		onClick={props.onSelect}
+	>
+		<span>{props.children}</span>
+	</button>
+);

package/vendor/stdlib/lib/modal.tsx

@@ -1,128 +1,35 @@
 /*
  * Copyright (C) 2024 Delusoire
+ * Copyright (C) 2026 Afonso Jorge Ramos
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
 import { React } from "../src/expose/React.ts";
-import { Locale } from "../src/webpack/misc.ts";
-
 import RootRegistry from "../src/registers/root.ts";
+import { Dialog } from "./primitives.tsx";
+
 const [RootChildrenRegistry] = RootRegistry;
-import { createIconComponent } from "../src/createIconComponent.tsx";
 
-let ref: React.ReactElement | undefined = undefined;
+export interface ModalOptions {
+	title: string;
+	content: React.ReactNode;
+	isLarge?: boolean;
+}
 
-export function display({ title, content, isLarge }: { title: string; content: React.ReactElement; isLarge: boolean }) {
-	hide();
+let mountedModal: React.ReactElement | undefined;
 
-	RootChildrenRegistry.add(
-		(ref = (
-			<PopupModal contentLabel={title} children={content} isEmbedWidgetGeneratorOrTrackCreditsModal={isLarge} />
-		)),
+export function display({ title, content, isLarge = false }: ModalOptions): void {
+	hide();
+	mountedModal = (
+		<Dialog title={title} size={isLarge ? "large" : "normal"} onClose={hide}>
+			{content}
+		</Dialog>
 	);
+	RootChildrenRegistry.add(mountedModal);
 }
 
-export function hide() {
-	if (ref) {
-		RootChildrenRegistry.delete(ref);
-		ref = undefined;
-	}
-}
-
-interface PopupModalProps {
-	contentLabel: string;
-	children: React.ReactNode;
-	isEmbedWidgetGeneratorOrTrackCreditsModal: boolean;
+export function hide(): void {
+	if (!mountedModal) return;
+	RootChildrenRegistry.delete(mountedModal);
+	mountedModal = undefined;
 }
-
-// Self-contained modal shell: client modal components (GenericModal, UI.*)
-// require the client tree's contexts, which anchors don't have. The shell
-// owns the backdrop and dismissal; the MAP-classed chrome keeps native
-// styling.
-const ModalShell = (props: { contentLabel: string; children: React.ReactNode }) => {
-	React.useEffect(() => {
-		const onKey = (e: KeyboardEvent) => {
-			if (e.key === "Escape") hide();
-		};
-		document.addEventListener("keydown", onKey);
-		return () => document.removeEventListener("keydown", onKey);
-	}, []);
-
-	return (
-		<div
-			role="dialog"
-			aria-label={props.contentLabel}
-			style={{
-				position: "fixed",
-				inset: 0,
-				zIndex: 100,
-				display: "flex",
-				alignItems: "center",
-				justifyContent: "center",
-				background: "rgba(0, 0, 0, 0.7)",
-			}}
-			onClick={(e) => {
-				if (e.target === e.currentTarget) hide();
-			}}
-		>
-			<div
-				style={{
-					background: "var(--spice-card, var(--background-elevated-base, #282828))",
-					color: "var(--spice-text, var(--text-base, #fff))",
-					borderRadius: "8px",
-					maxHeight: "80vh",
-					maxWidth: "90vw",
-					overflow: "auto",
-				}}
-			>
-				{props.children}
-			</div>
-		</div>
-	);
-};
-
-const closeIcon =
-	"<path d='M2.47 2.47a.75.75 0 0 1 1.06 0L8 6.94l4.47-4.47a.75.75 0 1 1 1.06 1.06L9.06 8l4.47 4.47a.75.75 0 1 1-1.06 1.06L8 9.06l-4.47 4.47a.75.75 0 0 1-1.06-1.06L6.94 8 2.47 3.53a.75.75 0 0 1 0-1.06Z'/>";
-
-const PopupModal = (props: PopupModalProps) => {
-	if (props.isEmbedWidgetGeneratorOrTrackCreditsModal) {
-		return (
-			<ModalShell contentLabel={props.contentLabel}>
-				<div className={MAP.modal.widget_generator.container} style={{ overflow: "scroll", width: "60vw" }}>
-					<div className={MAP.modal.widget_generator.header.container}>
-						<h1 className="encore-text encore-text-title-small">{props.contentLabel}</h1>
-						<button className={MAP.modal.widget_generator.header.close} onClick={hide}>
-							{createIconComponent({
-								icon: closeIcon,
-								"aria-label": Locale.get("close"),
-							})}
-						</button>
-					</div>
-					<div className={MAP.modal.widget_generator.content.container}>{props.children}</div>
-				</div>
-			</ModalShell>
-		);
-	}
-
-	return (
-		<ModalShell contentLabel={props.contentLabel}>
-			<div className={MAP.modal.track_credits.container}>
-				<div className={MAP.modal.track_credits.header.container}>
-					<h1 className="encore-text encore-text-title-medium">{props.contentLabel}</h1>
-					<button
-						className={MAP.modal.track_credits.header.close}
-						aria-label={Locale.get("close")}
-						onClick={hide}
-					>
-						{createIconComponent({
-							icon: closeIcon,
-							"aria-label": Locale.get("close"),
-							iconSize: 18,
-						})}
-					</button>
-				</div>
-				<div className={MAP.modal.track_credits.content.container}>{props.children}</div>
-			</div>
-		</ModalShell>
-	);
-};

package/vendor/stdlib/lib/popover.ts

@@ -10,6 +10,7 @@
 // modules can use it without touching React.
 
 import { React, ReactDOM } from "../src/expose/React.ts";
+import { calculateFloatingPosition } from "./floating-position.ts";
 
 export interface PopoverHandle {
 	close: () => void;
@@ -26,40 +27,40 @@ export interface PopoverOptions {
 export function openPopover({ anchor, content, onClose, gap = 8 }: PopoverOptions): PopoverHandle {
 	const host = document.createElement("div");
 	host.className = "spicetify-popover";
-	Object.assign(host.style, {
-		position: "fixed",
-		zIndex: "1000",
-		background: "var(--spice-card, var(--background-elevated-base, #282828))",
-		color: "var(--spice-text, var(--text-base, #fff))",
-		borderRadius: "8px",
-		boxShadow: "0 16px 24px rgba(0, 0, 0, 0.3), 0 6px 8px rgba(0, 0, 0, 0.2)",
-		maxHeight: "80vh",
-		overflow: "auto",
-	});
+	host.style.visibility = "hidden";
 
 	const place = () => {
-		const rect = anchor.getBoundingClientRect();
-		host.style.top = `${Math.round(Math.min(rect.bottom + gap, window.innerHeight - 64))}px`;
-		const left = Math.min(Math.max(8, rect.left), Math.max(8, window.innerWidth - host.offsetWidth - 8));
-		host.style.left = `${Math.round(left)}px`;
+		if (!anchor.isConnected || !host.isConnected) return;
+		const position = calculateFloatingPosition(
+			anchor.getBoundingClientRect(),
+			host.getBoundingClientRect(),
+			{ width: window.innerWidth, height: window.innerHeight },
+			{ align: "start", gap },
+		);
+		host.style.left = `${position.left}px`;
+		host.style.top = `${position.top}px`;
+		host.style.visibility = "visible";
+		host.dataset.placement = position.placement;
 	};
 
-	let root: { unmount: () => void } | undefined;
+	let root: ReturnType<typeof ReactDOM.createRoot> | undefined;
 	if (content instanceof HTMLElement) {
 		host.appendChild(content);
 	} else {
-		const createRoot = (ReactDOM as any).createRoot;
-		root = createRoot(host);
-		(root as any).render(React.createElement(React.Fragment, null, content as any));
+		root = ReactDOM.createRoot(host);
+		root.render(React.createElement(React.Fragment, null, content));
 	}
+	const resizeObserver = typeof ResizeObserver === "undefined" ? undefined : new ResizeObserver(place);
 
 	let closed = false;
 	const close = () => {
 		if (closed) return;
 		closed = true;
 		window.removeEventListener("resize", place);
+		document.removeEventListener("scroll", place, true);
 		document.removeEventListener("mousedown", onDocDown, true);
 		document.removeEventListener("keydown", onKey, true);
+		resizeObserver?.disconnect();
 		root?.unmount();
 		host.remove();
 		onClose?.();
@@ -69,7 +70,10 @@ export function openPopover({ anchor, content, onClose, gap = 8 }: PopoverOption
 		if (!host.contains(target) && !anchor.contains(target)) close();
 	};
 	const onKey = (e: KeyboardEvent) => {
-		if (e.key === "Escape") close();
+		if (e.key !== "Escape") return;
+		e.preventDefault();
+		e.stopPropagation();
+		close();
 	};
 
 	document.body.appendChild(host);
@@ -77,8 +81,11 @@ export function openPopover({ anchor, content, onClose, gap = 8 }: PopoverOption
 	// A second pass once layout has produced the real width, for clamping.
 	requestAnimationFrame(place);
 	window.addEventListener("resize", place);
+	document.addEventListener("scroll", place, true);
 	document.addEventListener("mousedown", onDocDown, true);
 	document.addEventListener("keydown", onKey, true);
+	resizeObserver?.observe(anchor);
+	resizeObserver?.observe(host);
 
 	return { close, host };
 }

package/vendor/stdlib/lib/primitives-classes.ts

@@ -33,6 +33,7 @@ export const SEARCHBAR_CLASS = "spicetify-searchbar";
 export const CARD_CLASS = "spicetify-card";
 export const SCRIM_CLASS = "spicetify-scrim";
 export const DIALOG_CLASS = "spicetify-dialog";
+export const DIALOG_LARGE_CLASS = "spicetify-dialog--large";
 export const DIALOG_HEADER_CLASS = "spicetify-dialog-header";
 export const DIALOG_BODY_CLASS = "spicetify-dialog-body";
 
@@ -43,6 +44,17 @@ export const SETTINGS_SECTION_CLASS = "x-settings-section";
 export const SETTINGS_ROW_CLASS = "x-settings-row";
 export const SETTINGS_ROW_LABEL_CLASS = "x-settings-firstColumn";
 export const SETTINGS_ROW_CONTROL_CLASS = "x-settings-secondColumn";
+export const SETTINGS_ACTION_GROUP_CLASS = "spicetify-settings-actions";
+export const SETTINGS_LABEL_COPY_CLASS = "spicetify-settings-label-copy";
+export const SETTINGS_HEADER_CONTAINER_CLASS = "x-settings-headerContainer";
+export const SETTINGS_HEADER_CLASS =
+	"encore-text encore-text-title-medium encore-internal-color-text-base x-settings-header";
+export const SETTINGS_SECTION_HEADING_CLASS =
+	"encore-text encore-text-body-medium-bold encore-internal-color-text-base spicetify-settings-section-heading";
+export const SETTINGS_SECTION_SUBHEADING_CLASS =
+	"encore-text encore-text-body-medium-bold encore-internal-color-text-base spicetify-settings-section-subheading";
+export const SETTINGS_ROW_TEXT_CLASS = "encore-text encore-text-body-small encore-internal-color-text-subdued";
+export const SETTINGS_HELP_TEXT_CLASS = "encore-text encore-text-marginal encore-internal-color-text-subdued";
 export const TOGGLE_CLASSES = {
 	wrapper: "x-toggle-wrapper",
 	input: "x-toggle-input",

package/vendor/stdlib/lib/primitives-vanilla.ts

@@ -27,11 +27,13 @@ import {
 	DIALOG_BODY_CLASS,
 	DIALOG_CLASS,
 	DIALOG_HEADER_CLASS,
+	DIALOG_LARGE_CLASS,
 	ICON_BUTTON_CLASS,
 	SCRIM_CLASS,
 	SEARCHBAR_CLASS,
 	SELECT_CLASS,
 } from "./primitives-classes.ts";
+import { activateDialog } from "./dialog-lifecycle.ts";
 
 export type { BadgeTone, ButtonVariant } from "./primitives-classes.ts";
 
@@ -246,22 +248,43 @@ export interface DialogHandle {
 // backdrop, close button, and programmatic close() all run one teardown,
 // so onClose fires exactly once on any dismissal path (consumers use it
 // to drop their own bookkeeping, e.g. a dispose registry).
-export function openDialog(props: { title: string; children: Child; onClose?: () => void }): DialogHandle {
+let nextDialogTitleId = 0;
+
+export function openDialog(props: {
+	title: string;
+	children: Child;
+	size?: "normal" | "large";
+	onClose?: () => void;
+}): DialogHandle {
 	const body = h("div", { className: DIALOG_BODY_CLASS }, props.children);
 	let closed = false;
+	let deactivate = () => {};
 	const close = () => {
 		if (closed) return;
 		closed = true;
+		deactivate();
 		scrim.remove();
 		props.onClose?.();
 	};
+	const titleId = `spicetify-dialog-title-${++nextDialogTitleId}`;
 	const header = h(
 		"div",
 		{ className: DIALOG_HEADER_CLASS },
-		h("h2", { textContent: props.title }),
+		h("h2", { id: titleId, textContent: props.title }),
 		IconButton({ glyph: "×", ariaLabel: "Close", onClick: close }),
 	);
-	const dialog = h("div", { className: DIALOG_CLASS }, header, body);
+	const dialog = h(
+		"div",
+		{
+			className: props.size === "large" ? `${DIALOG_CLASS} ${DIALOG_LARGE_CLASS}` : DIALOG_CLASS,
+			tabIndex: -1,
+			role: "dialog",
+			"aria-modal": "true",
+			"aria-labelledby": titleId,
+		},
+		header,
+		body,
+	);
 	const scrim = h(
 		"div",
 		{
@@ -273,5 +296,6 @@ export function openDialog(props: { title: string; children: Child; onClose?: ()
 		dialog,
 	);
 	document.body.append(scrim);
+	deactivate = activateDialog(dialog, close);
 	return { body, close };
 }