@spicetify/kit 0.1.0 → 0.3.0

package/vendor/shims/spicetify.d.ts

@@ -508,16 +508,28 @@ declare namespace Spicetify {
   const CosmosAPI: any;
   /**
    * Reaches hosts that refuse the client's origin, through the local daemon
-   * when it is running and the hosted proxy otherwise. Setting
-   * `spicetify:corsProxyTemplate` replaces the chain with that one template.
+   * when it is running and the hosted proxy otherwise. Its global
+   * configuration API can replace the chain with one custom template.
    */
   namespace CORSProxy {
+		type Mode = "automatic" | "custom";
+		interface Configuration {
+			mode: Mode;
+			template: string | null;
+			automaticTemplates: [string, string];
+		}
     /** The proxied URL for `target` using the first template in the chain. */
     function url(target: string): string;
     /** Fetches `target` proxied, falling back to the next template only when a request gets no answer. */
     function fetch(target: string, options?: RequestInit): Promise<Response>;
     /** The active chain, in order of preference. */
     function templates(): string[];
+		/** Describes the global proxy mode without exposing its storage details. */
+		function configuration(): Configuration;
+		/** Applies the automatic chain or a validated custom URL template immediately. */
+		function configure(options: { mode: "automatic" } | { mode: "custom"; template: string }): Configuration;
+		/** True when a custom absolute URL template contains the required `{url}` placeholder. */
+		function isValidTemplate(template: string): boolean;
   }
   /**
    * Async wrappers of CosmosAPI
@@ -819,12 +831,12 @@ declare namespace Spicetify {
   };
 
   /**
-   * The client's internal platform APIs. Typed from the generated
-   * PlatformAutoGen surface, exposing both the property form the client uses
-   * (`Platform.LibraryAPI`) and the generated `getLibraryAPI()` methods:
-   * every `getFooAPI(): R` yields a `FooAPI: R` property too.
+   * The client's internal platform APIs, typed from platform.d.ts, the
+   * committed snapshot scripts/platform-types.ts regenerates per Spotify
+   * build. The snapshot's root is the property form the client uses
+   * (`Platform.LibraryAPI`).
    */
-  type PlatformAutoGen = import("/hooks/PlatformAutoGen").PlatformAutoGen;
+  type PlatformAutoGen = import("./platform").Platform;
   // One level of member names per API — enough to autocomplete which methods an
   // API exposes (Platform.LibraryAPI.getContents…), with every value left `any`.
   // The generated method signatures are unreliable (arg counts and nullability
@@ -836,22 +848,10 @@ declare namespace Spicetify {
     : T extends object
       ? { [M in keyof T]: any }
       : T;
-  // Both forms the client offers: the getFooAPI() methods (permissive args,
-  // shaped return) and each getFooAPI(): R also as a FooAPI: R property (the
-  // form the client uses). The Record<string, any> tail keeps unknown keys open.
-  type PlatformApis =
-    & {
-        [K in keyof PlatformAutoGen]: PlatformAutoGen[K] extends (...args: any[]) => infer R
-          ? (...args: any[]) => Shape<R>
-          : PlatformAutoGen[K];
-      }
-    & {
-        [K in keyof PlatformAutoGen as K extends `get${infer Name}` ? Name : never]: PlatformAutoGen[K] extends (
-          ...args: any[]
-        ) => infer R
-          ? Shape<R>
-          : never;
-      };
+  // The Record<string, any> tail keeps unknown keys open.
+  type PlatformApis = {
+    [K in keyof PlatformAutoGen]: Shape<PlatformAutoGen[K]>;
+  };
   const Platform: PlatformApis & Record<string, any>;
   /**
    * Queue object contains list of queuing tracks,

package/vendor/stdlib/lib/dialog-lifecycle.ts

@@ -0,0 +1,53 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+const FOCUSABLE_SELECTOR = [
+	"button:not([disabled])",
+	"[href]",
+	"input:not([disabled])",
+	"select:not([disabled])",
+	"textarea:not([disabled])",
+	'[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+const focusableElements = (dialog: HTMLElement): HTMLElement[] =>
+	[...dialog.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)].filter(
+		(element) => !element.hidden && element.getAttribute("aria-hidden") !== "true",
+	);
+
+export function activateDialog(dialog: HTMLElement, close: () => void): () => void {
+	const previousFocus = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+	const onKeyDown = (event: KeyboardEvent) => {
+		if (event.key === "Escape") {
+			event.preventDefault();
+			event.stopPropagation();
+			close();
+			return;
+		}
+		if (event.key !== "Tab") return;
+		const focusable = focusableElements(dialog);
+		if (focusable.length === 0) {
+			event.preventDefault();
+			dialog.focus();
+			return;
+		}
+		const first = focusable[0];
+		const last = focusable.at(-1)!;
+		if (event.shiftKey && document.activeElement === first) {
+			event.preventDefault();
+			last.focus();
+		} else if (!event.shiftKey && document.activeElement === last) {
+			event.preventDefault();
+			first.focus();
+		}
+	};
+
+	document.addEventListener("keydown", onKeyDown, true);
+	(focusableElements(dialog)[0] ?? dialog).focus();
+	return () => {
+		document.removeEventListener("keydown", onKeyDown, true);
+		if (previousFocus?.isConnected) previousFocus.focus();
+	};
+}

package/vendor/stdlib/lib/floating-position.ts

@@ -0,0 +1,57 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+export interface AnchorRect {
+	left: number;
+	top: number;
+	right: number;
+	bottom: number;
+}
+
+export interface SurfaceSize {
+	width: number;
+	height: number;
+}
+
+export interface ViewportSize {
+	width: number;
+	height: number;
+}
+
+export interface FloatingPositionOptions {
+	align: "center" | "start";
+	gap: number;
+	margin?: number;
+}
+
+export interface FloatingPosition {
+	left: number;
+	top: number;
+	placement: "above" | "below";
+}
+
+const clamp = (value: number, minimum: number, maximum: number): number =>
+	Math.min(Math.max(value, minimum), Math.max(minimum, maximum));
+
+export function calculateFloatingPosition(
+	anchor: AnchorRect,
+	surface: SurfaceSize,
+	viewport: ViewportSize,
+	options: FloatingPositionOptions,
+): FloatingPosition {
+	const margin = options.margin ?? 8;
+	const spaceBelow = viewport.height - anchor.bottom - margin;
+	const spaceAbove = anchor.top - margin;
+	const placement = spaceBelow >= surface.height + options.gap || spaceBelow >= spaceAbove ? "below" : "above";
+	const desiredTop = placement === "below" ? anchor.bottom + options.gap : anchor.top - options.gap - surface.height;
+	const anchorCenter = anchor.left + (anchor.right - anchor.left) / 2;
+	const desiredLeft = options.align === "center" ? anchorCenter - surface.width / 2 : anchor.left;
+
+	return {
+		left: Math.round(clamp(desiredLeft, margin, viewport.width - surface.width - margin)),
+		top: Math.round(clamp(desiredTop, margin, viewport.height - surface.height - margin)),
+		placement,
+	};
+}

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>
-	);
-};