@spicetify/kit 0.1.0 → 0.3.0

package/vendor/stdlib/src/registers/index.ts

@@ -11,16 +11,22 @@ import menu from "./menu.ts";
 import { mountAdjacent } from "./mount.ts";
 import { isNativeAnchor, type NativeAnchor, resolveNativeAnchor } from "./nativeAnchors.ts";
 import navlink from "./navlink.tsx";
-import panel from "./panel.ts";
+import panel, { type PanelController, type PanelRegistration } from "./panel.ts";
 import playbarButton, { PlaybarButton } from "./playbarButton.tsx";
 import playbarWidget from "./playbarWidget.tsx";
 import { Registry } from "./registry.ts";
 import root from "./root.ts";
 import route from "./route.ts";
 import settingsRow from "./settingsRow.tsx";
-import settingsSection from "./settingsSection.ts";
+import settingsSection, { settingsAction } from "./settingsSection.ts";
 import topbarLeftButton, { TopbarLeftButton } from "./topbarLeftButton.tsx";
 import topbarRightButton, { TopbarRightButton } from "./topbarRightButton.tsx";
+export type { PanelController, PanelRegistration, PanelWidth } from "./panel.ts";
+export { closeMenu, openedFromProfileMenu, useMenuItem } from "./menu.ts";
+export { NavLink, type NavLinkProps, useHistoryRefresh } from "./navlink.tsx";
+export { PlaybarButton, type PlaybarButtonProps } from "./playbarButton.tsx";
+export { TopbarLeftButton } from "./topbarLeftButton.tsx";
+export { TopbarRightButton } from "./topbarRightButton.tsx";
 const [rootChild, rootProvider] = root;
 const registers = {
 	menu,
@@ -32,12 +38,15 @@ const registers = {
 	rootProvider,
 	route,
 	settingsRow,
+	settingsAction,
 	settingsSection,
 	topbarLeftButton,
 	topbarRightButton,
 } satisfies Record<string, Registry<any>>;
 type Registers = typeof registers;
 
+export { SPICETIFY_SETTINGS_ROUTE } from "./settingsSection.ts";
+
 // ---- placeButton: one ergonomic, position-controllable way to add a button ----
 // Instead of picking the right register key and hand-building the matching
 // component (easy to mismatch, no ordering), a module names a location and
@@ -52,7 +61,7 @@ export interface PlaceButtonOptions {
 	label: string;
 	/** Inner SVG markup drawn on the stdlib 16-grid. */
 	icon?: string;
-	onClick: () => void;
+	onClick: (event: React.MouseEvent<HTMLButtonElement>) => void;
 	disabled?: boolean;
 	/** Position within this slot's module buttons; lower renders earlier. Default 0. */
 	order?: number;
@@ -73,6 +82,11 @@ export interface ButtonHandle {
 	remove(): void;
 }
 
+export interface RegisterPanelOptions extends Omit<PanelRegistration<React.ReactNode>, "id"> {
+	/** Stable within this module. Defaults to "default". */
+	id?: string;
+}
+
 const BUTTON_SLOTS = {
 	"topbar-left": ["topbarLeftButton", TopbarLeftButton],
 	"topbar-right": ["topbarRightButton", TopbarRightButton],
@@ -139,6 +153,29 @@ export class Registrar {
 		};
 	}
 
+	/**
+	 * Register a Spicetify-owned right-sidebar panel. The returned controller
+	 * opens, closes and observes the panel; module unload disposes it.
+	 */
+	registerPanel(options: RegisterPanelOptions): PanelController {
+		const registration: PanelRegistration<React.ReactNode> = {
+			...options,
+			id: `${this.id}:${options.id ?? "default"}`,
+		};
+		panel.add(registration);
+		const controller = panel.controller(registration);
+		if (!controller) throw new Error(`[stdlib] failed to register panel: ${registration.id}`);
+		const dispose = () => panel.delete(registration);
+		this.disposers.add(dispose);
+		return {
+			...controller,
+			dispose: () => {
+				this.disposers.delete(dispose);
+				dispose();
+			},
+		};
+	}
+
 	register<R extends keyof Registers>(type: R, ...args: Parameters<Registers[R]["add"]>) {
 		this.ledger.set(args[0], type);
 		// @ts-ignore

package/vendor/stdlib/src/registers/panel-logic.ts

@@ -0,0 +1,371 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+export interface PanelWidth {
+	default?: number;
+	min?: number;
+	max?: number;
+}
+
+export interface PanelRegistration<Content = unknown> {
+	id: string;
+	label: string;
+	render: () => Content;
+	width?: PanelWidth;
+	onOpen?: () => void;
+	onClose?: () => void;
+}
+
+export interface PanelController {
+	open(): void;
+	close(): void;
+	toggle(): void;
+	isOpen(): boolean;
+	subscribe(listener: (open: boolean) => void): () => void;
+	dispose(): void;
+}
+
+export interface PanelCoordinatorOptions<Content = unknown> {
+	document: Document;
+	window: Window;
+	mount(host: HTMLElement, panel: PanelRegistration<Content>, close: () => void): () => void;
+}
+
+export interface PanelCoordinator<Content = unknown> {
+	register(panel: PanelRegistration<Content>): PanelController;
+	dispose(): void;
+}
+
+type RegistrationState<Content> = {
+	panel: PanelRegistration<Content>;
+	disposed: boolean;
+	listeners: Set<(open: boolean) => void>;
+};
+
+type NativeSnapshot = { hidden: string | null; inert: string | null };
+type StyleSnapshot = { value: string; priority: string };
+
+const WIDTH_DEFAULT = 360;
+const WIDTH_MIN = 280;
+const WIDTH_MAX = 520;
+
+const panelWidth = ({ width }: PanelRegistration): number => {
+	const min = width?.min ?? WIDTH_MIN;
+	const max = Math.max(min, width?.max ?? WIDTH_MAX);
+	return Math.min(max, Math.max(min, width?.default ?? WIDTH_DEFAULT));
+};
+
+const validatePanelWidth = (width: PanelWidth | undefined) => {
+	if (!width) return;
+	for (const key of ["default", "min", "max"] as const) {
+		const value = width[key];
+		if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
+			throw new Error(`[stdlib] panel width ${key} must be a finite non-negative number`);
+		}
+	}
+};
+
+const gridTracks = (template: string): string[] => {
+	const tracks: string[] = [];
+	let token = "";
+	let parentheses = 0;
+	let brackets = 0;
+	for (const character of template.trim()) {
+		if (/\s/.test(character) && parentheses === 0 && brackets === 0) {
+			if (token) tracks.push(token);
+			token = "";
+			continue;
+		}
+		token += character;
+		if (character === "(") parentheses += 1;
+		else if (character === ")") parentheses -= 1;
+		else if (character === "[") brackets += 1;
+		else if (character === "]") brackets -= 1;
+	}
+	if (token) tracks.push(token);
+	return tracks.filter((track) => !(track.startsWith("[") && track.endsWith("]")));
+};
+
+export function createPanelCoordinator<Content = unknown>(options: PanelCoordinatorOptions<Content>) {
+	const registrations = new Map<string, RegistrationState<Content>>();
+	const suspended = new Map<HTMLElement, NativeSnapshot>();
+	const ownedStyles = new Map<HTMLElement, Map<string, StyleSnapshot>>();
+	let active: RegistrationState<Content> | undefined;
+	let activeHost: HTMLElement | undefined;
+	let activeSidebar: HTMLElement | undefined;
+	let activeTopContainer: HTMLElement | undefined;
+	let unmount: (() => void) | undefined;
+	let shellObserver: MutationObserver | undefined;
+	let sidebarObserver: MutationObserver | undefined;
+	let returnFocus: HTMLElement | undefined;
+	let disposed = false;
+	let transitioning = false;
+	const transitions: Array<() => void> = [];
+	const Observer = (options.window as unknown as { MutationObserver: typeof MutationObserver }).MutationObserver;
+
+	const safely = (label: string, callback: (() => void) | undefined) => {
+		if (!callback) return;
+		try {
+			callback();
+		} catch (error) {
+			console.error(`[stdlib] panel ${label} failed:`, error);
+		}
+	};
+
+	const notify = (state: RegistrationState<Content>, open: boolean) => {
+		for (const listener of state.listeners) safely("subscriber", () => listener(open));
+	};
+
+	const transition = (action: () => void) => {
+		transitions.push(action);
+		if (transitioning) return;
+		transitioning = true;
+		let firstError: unknown;
+		try {
+			let next: (() => void) | undefined;
+			while ((next = transitions.shift())) {
+				try {
+					next();
+				} catch (error) {
+					firstError ??= error;
+				}
+			}
+		} finally {
+			transitioning = false;
+		}
+		if (firstError) throw firstError;
+	};
+
+	const restoreNative = () => {
+		for (const [element, snapshot] of suspended) {
+			for (const attribute of ["hidden", "inert"] as const) {
+				const value = snapshot[attribute];
+				if (value === null) element.removeAttribute(attribute);
+				else element.setAttribute(attribute, value);
+			}
+		}
+		suspended.clear();
+	};
+
+	const setOwnedStyle = (element: HTMLElement, property: string, value: string) => {
+		let snapshots = ownedStyles.get(element);
+		if (!snapshots) {
+			snapshots = new Map();
+			ownedStyles.set(element, snapshots);
+		}
+		if (!snapshots.has(property)) {
+			snapshots.set(property, {
+				value: element.style.getPropertyValue(property),
+				priority: element.style.getPropertyPriority(property),
+			});
+		}
+		element.style.setProperty(property, value, "important");
+	};
+
+	const restoreOwnedStyles = (element: HTMLElement | undefined) => {
+		if (!element) return;
+		const snapshots = ownedStyles.get(element);
+		if (!snapshots) return;
+		for (const [property, snapshot] of snapshots) {
+			if (snapshot.value) element.style.setProperty(property, snapshot.value, snapshot.priority);
+			else element.style.removeProperty(property);
+		}
+		ownedStyles.delete(element);
+	};
+
+	const suspendNative = (sidebar: HTMLElement) => {
+		for (const child of sidebar.children) {
+			if (!(child instanceof HTMLElement) || child === activeHost) continue;
+			if (!suspended.has(child)) {
+				suspended.set(child, { hidden: child.getAttribute("hidden"), inert: child.getAttribute("inert") });
+			}
+			child.setAttribute("hidden", "");
+			child.setAttribute("inert", "");
+		}
+	};
+
+	const observeSidebar = (sidebar: HTMLElement) => {
+		sidebarObserver?.disconnect();
+		sidebarObserver = new Observer(() => suspendNative(sidebar));
+		sidebarObserver.observe(sidebar, { childList: true });
+	};
+
+	const clearLayout = () => {
+		activeTopContainer?.removeAttribute("data-spicetify-panel-active");
+		restoreOwnedStyles(activeTopContainer);
+		restoreOwnedStyles(activeSidebar);
+		activeTopContainer = undefined;
+		activeSidebar = undefined;
+	};
+
+	const placeActiveHost = (): boolean => {
+		if (!active || !activeHost) return false;
+		const sidebar = options.document.querySelector<HTMLElement>(".Root__right-sidebar");
+		const topContainer = options.document.querySelector<HTMLElement>(".Root__top-container");
+		if (!sidebar || !topContainer) return false;
+
+		if (activeSidebar !== sidebar) {
+			restoreNative();
+			restoreOwnedStyles(activeSidebar);
+			activeSidebar = sidebar;
+			observeSidebar(sidebar);
+		}
+		if (activeHost.parentElement !== sidebar) sidebar.prepend(activeHost);
+		if (activeTopContainer !== topContainer) {
+			activeTopContainer?.removeAttribute("data-spicetify-panel-active");
+			restoreOwnedStyles(activeTopContainer);
+			activeTopContainer = topContainer;
+		}
+		topContainer.dataset.spicetifyPanelActive = "";
+		const trailingTracks = gridTracks(options.window.getComputedStyle(topContainer).gridTemplateColumns).slice(3);
+		const trailingWidth = trailingTracks.reduce(
+			(total, track) => total + (track.endsWith("px") ? Number.parseFloat(track) || 0 : 0),
+			0,
+		);
+		setOwnedStyle(topContainer, "--spicetify-panel-requested-width", `${panelWidth(active.panel)}px`);
+		setOwnedStyle(topContainer, "--spicetify-panel-trailing-width", `${trailingWidth}px`);
+		setOwnedStyle(
+			topContainer,
+			"grid-template-columns",
+			["auto", "minmax(0, 1fr)", "var(--spicetify-panel-width)", ...trailingTracks].join(" "),
+		);
+		setOwnedStyle(sidebar, "width", "var(--spicetify-panel-width)");
+		setOwnedStyle(sidebar, "min-width", "var(--spicetify-panel-width)");
+		suspendNative(sidebar);
+		return true;
+	};
+
+	const closeActive = (restoreFocus: boolean) => {
+		const closing = active;
+		if (!closing) return;
+		active = undefined;
+		shellObserver?.disconnect();
+		shellObserver = undefined;
+		sidebarObserver?.disconnect();
+		sidebarObserver = undefined;
+		safely("unmount", unmount);
+		unmount = undefined;
+		activeHost?.remove();
+		activeHost = undefined;
+		restoreNative();
+		clearLayout();
+		safely("onClose", closing.panel.onClose);
+		notify(closing, false);
+		if (restoreFocus) {
+			if (returnFocus?.isConnected) returnFocus.focus();
+			returnFocus = undefined;
+		}
+	};
+
+	const open = (state: RegistrationState<Content>) => {
+		if (disposed || state.disposed) return;
+		if (active === state) return;
+		const replacing = !!active;
+		if (replacing) closeActive(false);
+		const focused = options.document.activeElement;
+		if (!replacing) returnFocus = focused instanceof HTMLElement ? focused : undefined;
+		active = state;
+		activeHost = options.document.createElement("section");
+		activeHost.className = "spicetify-panel-host";
+		activeHost.dataset.panelId = state.panel.id;
+		activeHost.setAttribute("role", "complementary");
+		activeHost.setAttribute("aria-label", state.panel.label);
+		activeHost.tabIndex = -1;
+		try {
+			unmount = options.mount(activeHost, state.panel, () => transition(() => closeActive(true)));
+		} catch (error) {
+			active = undefined;
+			activeHost.remove();
+			activeHost = undefined;
+			if (returnFocus?.isConnected) returnFocus.focus();
+			returnFocus = undefined;
+			throw error;
+		}
+		placeActiveHost();
+		shellObserver = new Observer(() => {
+			if (activeHost?.isConnected && activeSidebar?.isConnected && activeTopContainer?.isConnected) return;
+			placeActiveHost();
+		});
+		if (options.document.body) shellObserver.observe(options.document.body, { childList: true, subtree: true });
+		safely("onOpen", state.panel.onOpen);
+		notify(state, true);
+		activeHost.focus();
+	};
+
+	const onKeyDown = (event: KeyboardEvent) => {
+		if (event.key !== "Escape" || event.defaultPrevented || !active) return;
+		if (
+			options.document.querySelector(
+				".spicetify-popover, .spicetify-scrim, .spicetify-root-children [role='dialog']",
+			)
+		)
+			return;
+		event.preventDefault();
+		transition(() => closeActive(true));
+	};
+	options.document.addEventListener("keydown", onKeyDown);
+
+	const register = (panel: PanelRegistration<Content>): PanelController => {
+		if (disposed) throw new Error("[stdlib] panel coordinator is disposed");
+		if (!panel.id.trim()) throw new Error("[stdlib] panel id must not be empty");
+		if (!panel.label.trim()) throw new Error("[stdlib] panel label must not be empty");
+		validatePanelWidth(panel.width);
+		if (registrations.has(panel.id)) throw new Error(`[stdlib] duplicate panel id: ${panel.id}`);
+		const state: RegistrationState<Content> = { panel, disposed: false, listeners: new Set() };
+		registrations.set(panel.id, state);
+
+		return {
+			open: () => {
+				if (disposed || state.disposed) throw new Error(`[stdlib] panel "${state.panel.id}" is disposed`);
+				transition(() => open(state));
+			},
+			close: () => {
+				transition(() => {
+					if (active === state) closeActive(true);
+				});
+			},
+			toggle: () => {
+				if (disposed || state.disposed) throw new Error(`[stdlib] panel "${state.panel.id}" is disposed`);
+				transition(() => {
+					if (active === state) closeActive(true);
+					else open(state);
+				});
+			},
+			isOpen: () => active === state,
+			subscribe(listener) {
+				if (state.disposed) throw new Error(`[stdlib] panel "${state.panel.id}" is disposed`);
+				state.listeners.add(listener);
+				safely("subscriber", () => listener(active === state));
+				return () => state.listeners.delete(listener);
+			},
+			dispose() {
+				if (state.disposed) return;
+				state.disposed = true;
+				transition(() => {
+					if (active === state) closeActive(true);
+					state.listeners.clear();
+					registrations.delete(panel.id);
+				});
+			},
+		};
+	};
+
+	const dispose = () => {
+		if (disposed) return;
+		disposed = true;
+		transition(() => {
+			closeActive(false);
+			returnFocus = undefined;
+			for (const state of registrations.values()) {
+				state.disposed = true;
+				state.listeners.clear();
+			}
+			registrations.clear();
+			options.document.removeEventListener("keydown", onKeyDown);
+		});
+	};
+
+	return { register, dispose } satisfies PanelCoordinator<Content>;
+}

package/vendor/stdlib/src/registers/panel.ts

@@ -1,168 +1,80 @@
 /*
  * Copyright (C) 2024 Delusoire
+ * Copyright (C) 2026 Afonso Jorge Ramos
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
-import { transformer } from "../../mixin.ts";
-
-import type { createMachine as createMachineT } from "npm:xstate";
+import { React, ReactDOM } from "../expose/React.ts";
+import { createItemBoundary } from "./mount.ts";
 import { Registry } from "./registry.ts";
-
-export type StateMachine = ReturnType<typeof createMachineT>;
-export let Machine: StateMachine;
-
-const registry = new (class extends Registry<React.ReactNode> {
-	private static NodeNash = Symbol.for("NodeHash");
-
-	getHash(value: React.ReactNode) {
-		if (!this.has(value)) {
-			return null;
-		}
-		// @ts-ignore
-		const hash = value[this.constructor.NodeNash];
-		const state = `bespoke_${hash}`;
-		const event = `bespoke_${hash}_button_click`;
-		return { state, event };
-	}
-
-	override add(value: React.ReactNode, onEntry?: any, onExit?: any): this {
-		const hash = crypto.randomUUID();
-		// @ts-ignore
-		value[this.constructor.NodeNash] = hash;
-		const state = `bespoke_${hash}`;
-		const event = `bespoke_${hash}_button_click`;
-
-		stateToNode.set(state, value);
-
-		ON[event] = {
-			target: state,
-		};
-
-		STATES[state] = {
-			on: Object.setPrototypeOf(
-				{
-					[event]: {
-						target: "disabled",
+import {
+	createPanelCoordinator,
+	type PanelController,
+	type PanelCoordinator,
+	type PanelRegistration,
+} from "./panel-logic.ts";
+
+export type { PanelController, PanelRegistration, PanelWidth } from "./panel-logic.ts";
+
+const mountReactPanel = (host: HTMLElement, panel: PanelRegistration<React.ReactNode>, close: () => void) => {
+	const root = ReactDOM.createRoot(host);
+	const PanelBoundary = createItemBoundary(React, "panel") as unknown as React.ComponentType<{
+		children?: React.ReactNode;
+	}>;
+	const PanelContent = () => React.createElement("div", { className: "spicetify-panel-content" }, panel.render());
+	const PanelSurface = () =>
+		React.createElement(
+			React.Fragment,
+			null,
+			React.createElement(
+				"header",
+				{ className: "spicetify-panel-header" },
+				React.createElement("h2", { className: "spicetify-panel-title" }, panel.label),
+				React.createElement(
+					"button",
+					{
+						className: "spicetify-panel-close spicetify-button-circle",
+						"aria-label": `Close ${panel.label}`,
+						onClick: close,
 					},
-				},
-				ON,
+					"×",
+				),
 			),
-		};
-
-		if (onEntry) {
-			const entry = `bespoke_${hash}_entry`;
-			STATES[state].entry = [entry];
-			ACTIONS[entry] = onEntry;
-		}
-		if (onExit) {
-			const exit = `bespoke_${hash}_exit`;
-			Machine.config.states![state].exit = [exit];
-			ACTIONS[exit] = onExit;
-		}
+			React.createElement(PanelBoundary, null, React.createElement(PanelContent)),
+		);
+	root.render(React.createElement(PanelSurface));
+	return () => root.unmount();
+};
 
-		return super.add(value);
-	}
+const panelCoordinatorKey = Symbol.for("spicetify.stdlib.panel-coordinator");
+const shared = globalThis as typeof globalThis & Record<symbol, unknown>;
+const previousCoordinator = shared[panelCoordinatorKey] as PanelCoordinator<React.ReactNode> | undefined;
+previousCoordinator?.dispose();
 
-	override delete(item: React.ReactNode): boolean {
-		// @ts-ignore
-		const hash = item[this.constructor.NodeNash];
-		const state = `bespoke_${hash}`;
-		const event = `bespoke_${hash}_button_click`;
+export const panelCoordinator = createPanelCoordinator<React.ReactNode>({
+	document,
+	window,
+	mount: mountReactPanel,
+});
+shared[panelCoordinatorKey] = panelCoordinator;
 
-		stateToNode.delete(state);
+class PanelRegistry extends Registry<PanelRegistration<React.ReactNode>> {
+	private controllers = new Map<PanelRegistration<React.ReactNode>, PanelController>();
 
-		delete ON[event];
-		return super.delete(item);
+	override add(panel: PanelRegistration<React.ReactNode>): this {
+		this.controllers.set(panel, panelCoordinator.register(panel));
+		return super.add(panel);
 	}
-})();
-export default registry;
-
-const stateToNode = new Map<string, React.ReactNode>();
-
-declare global {
-	var __renderPanel: any;
-}
 
-globalThis.__renderPanel = (state: string) => {
-	if (!state.startsWith("bespoke_")) {
-		return null;
+	override delete(panel: PanelRegistration<React.ReactNode>): boolean {
+		this.controllers.get(panel)?.dispose();
+		this.controllers.delete(panel);
+		return super.delete(panel);
 	}
 
-	return stateToNode.get(state);
-};
-
-let ON: Record<string, any> = {};
-let STATES: Record<string, any> = {};
-let ACTIONS: Record<string, any> = {};
-
-transformer(
-	(emit) => (str) => {
-		emit();
-
-		str = str.replace(/(=\(0,[a-zA-Z_\$][\w\$]*\.[a-zA-Z_\$][\w\$]*\)\(\{id:"RightPanelState)/, "=__Machine$1");
-		Object.defineProperty(globalThis, "__Machine", {
-			set: ($: StateMachine) => {
-				Machine = $;
-
-				queueMicrotask(() => {
-					ON = {
-						...ON,
-						...Machine.config.states!.disabled.on,
-						panel_close_click: [
-							{
-								target: "disabled",
-							},
-						],
-					};
-					delete ON.playback_autoplay_context_changed;
-
-					for (const [k, v] of Object.entries(Machine.config.states! as Record<string, any>)) {
-						if (k === "puffin_activation") {
-							continue;
-						}
-						v.on = new Proxy(v.on!, {
-							get(target, p, _receiver) {
-								// @ts-ignore
-								if (p.startsWith("bespoke_")) {
-									// @ts-ignore
-									return ON[p];
-								}
-								// @ts-ignore
-								return target[p];
-							},
-						});
-					}
-
-					Object.setPrototypeOf(Machine.config.states!, STATES);
-
-					Machine._options.actions = ACTIONS;
-				});
-			},
-			get: () => Machine,
-		});
-
-		// ! HACKY ALERT
-		str = str.replace(
-			/(case [a-zA-Z_\$][\w\$]*\.[a-zA-Z_\$][\w\$]*\.Disabled:return!0;default:)/,
-			"$1return true;",
-		);
-
-		return str;
-	},
-	{
-		glob: /^\/xpui\.js/,
-	},
-);
-
-transformer(
-	(emit) => (str) => {
-		emit();
-
-		str = str.replace(/(\(([a-zA-Z_\$][\w\$]*),"PanelSection".+?children:\[?)/, "$1__renderPanel($2),");
+	controller(panel: PanelRegistration<React.ReactNode>): PanelController | undefined {
+		return this.controllers.get(panel);
+	}
+}
 
-		return str;
-	},
-	{
-		glob: /^\/dwp\-panel\-section\.js/,
-	},
-);
+export default new PanelRegistry();