@spicetify/kit 0.1.0

package/vendor/stdlib/src/playbar-compat.tsx

@@ -0,0 +1,136 @@
+/*
+ * Copyright (C) 2026 Afonso Jorge Ramos
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+// The client still exposes the classic Spicetify.Playbar.Button/Widget, but
+// they no longer mount in the restructured playbar (they construct a DOM node
+// that is never inserted). Every other v2 helper (Menu, ContextMenu, Topbar,
+// Keyboard, PopupModal, ...) still works, so this is the one gap. We re-back
+// Button/Widget with the v3 playbarButton register so classic extensions and
+// muscle memory keep working, and the typed API never hands you a dead helper.
+
+import { React } from "./expose/React.ts";
+import playbarButtons, { PlaybarButton } from "./registers/playbarButton.tsx";
+
+// The register feeds `icon` to createIconComponent, which supplies its own
+// <svg> wrapper. Classic icons are full <svg>...</svg> strings, so hand it the
+// inner markup; already-inner markup passes through untouched.
+const innerSvg = (icon: string): string => {
+	const match = /<svg[^>]*>([\s\S]*)<\/svg>/i.exec(icon);
+	return match ? match[1] : icon;
+};
+
+class PlaybarCompat {
+	onClick: (self: PlaybarCompat) => void;
+	private _label: string;
+	private _icon: string;
+	private _active: boolean;
+	private _disabled: boolean;
+	private node: React.ReactNode | null = null;
+	private readonly refreshers = new Set<() => void>();
+
+	constructor(
+		label: string,
+		icon: string,
+		onClick: (self: PlaybarCompat) => void = () => {},
+		disabled = false,
+		active = false,
+		registerOnCreate = true,
+	) {
+		this._label = label;
+		this._icon = icon;
+		this.onClick = onClick;
+		this._disabled = disabled;
+		this._active = active;
+		if (registerOnCreate) this.register();
+	}
+
+	private refresh() {
+		for (const f of this.refreshers) f();
+	}
+
+	// Mutating any display field re-renders the mounted button, matching the
+	// classic API where `widget.active = true` / `widget.label = "..."` update live.
+	get label() {
+		return this._label;
+	}
+	set label(v) {
+		this._label = v;
+		this.refresh();
+	}
+	get icon() {
+		return this._icon;
+	}
+	set icon(v) {
+		this._icon = v;
+		this.refresh();
+	}
+	get active() {
+		return this._active;
+	}
+	set active(v) {
+		this._active = v;
+		this.refresh();
+	}
+	get disabled() {
+		return this._disabled;
+	}
+	set disabled(v) {
+		this._disabled = v;
+		this.refresh();
+	}
+	// No standalone DOM node in the register model; classic code rarely touches these.
+	get element(): HTMLButtonElement | null {
+		return null;
+	}
+	get tippy(): unknown {
+		return null;
+	}
+
+	register() {
+		if (this.node) return;
+		const self = this;
+		const Compat = () => {
+			const [, force] = React.useReducer((n: number) => n + 1, 0);
+			React.useEffect(() => {
+				self.refreshers.add(force);
+				return () => {
+					self.refreshers.delete(force);
+				};
+			}, []);
+			return (
+				<PlaybarButton
+					label={self._label}
+					icon={innerSvg(self._icon)}
+					isActive={self._active}
+					disabled={self._disabled}
+					onClick={() => self.onClick(self)}
+				/>
+			);
+		};
+		this.node = <Compat />;
+		playbarButtons.add(this.node);
+	}
+
+	deregister() {
+		if (!this.node) return;
+		playbarButtons.delete(this.node);
+		this.node = null;
+	}
+}
+
+// Replace the client's dead Button/Widget with the register-backed shim.
+// Returns a teardown that restores the originals.
+export function installPlaybarCompat(): () => void {
+	const S = (globalThis as { Spicetify?: { Playbar?: Record<string, unknown> } }).Spicetify;
+	if (!S?.Playbar) return () => {};
+	const original = { Button: S.Playbar.Button, Widget: S.Playbar.Widget };
+	S.Playbar.Button = PlaybarCompat;
+	S.Playbar.Widget = PlaybarCompat;
+	return () => {
+		if (!S.Playbar) return;
+		S.Playbar.Button = original.Button;
+		S.Playbar.Widget = original.Widget;
+	};
+}

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

@@ -0,0 +1,176 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import type { ModuleRuntimeContext } from "../../mod.ts";
+
+import { React } from "../expose/React.ts";
+import { warn } from "../logger.ts";
+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 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 topbarLeftButton, { TopbarLeftButton } from "./topbarLeftButton.tsx";
+import topbarRightButton, { TopbarRightButton } from "./topbarRightButton.tsx";
+const [rootChild, rootProvider] = root;
+const registers = {
+	menu,
+	navlink,
+	panel,
+	playbarButton,
+	playbarWidget,
+	rootChild,
+	rootProvider,
+	route,
+	settingsRow,
+	settingsSection,
+	topbarLeftButton,
+	topbarRightButton,
+} satisfies Record<string, Registry<any>>;
+type Registers = typeof registers;
+
+// ---- 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
+// passes the button's props in one call. `order` controls position within the
+// group of module buttons in that slot (lower renders earlier).
+
+/** Where a module button can live. */
+export type ButtonLocation = "topbar-left" | "topbar-right" | "playbar";
+
+export interface PlaceButtonOptions {
+	/** Tooltip + accessible label. */
+	label: string;
+	/** Inner SVG markup drawn on the stdlib 16-grid. */
+	icon?: string;
+	onClick: () => void;
+	disabled?: boolean;
+	/** Position within this slot's module buttons; lower renders earlier. Default 0. */
+	order?: number;
+	/** Playbar only: render the active indicator. Ignored in the top bar. */
+	isActive?: boolean;
+	/**
+	 * Place the button next to one of the client's own buttons instead of in the
+	 * module-button group. `anchor` is a stable stdlib-owned name (e.g.
+	 * "playbar:queue"); if it can't be resolved on this client the button falls
+	 * back to ordinary `order` placement, so it is never hidden. `side` defaults
+	 * to "after".
+	 */
+	near?: { anchor: NativeAnchor; side?: "before" | "after" };
+}
+
+export interface ButtonHandle {
+	/** Remove the button now. It is also removed automatically when the module unloads. */
+	remove(): void;
+}
+
+const BUTTON_SLOTS = {
+	"topbar-left": ["topbarLeftButton", TopbarLeftButton],
+	"topbar-right": ["topbarRightButton", TopbarRightButton],
+	playbar: ["playbarButton", PlaybarButton],
+} as const satisfies Record<ButtonLocation, [keyof Registers, React.FC<any>]>;
+
+export class Registrar {
+	constructor(public id: string) {}
+
+	private ledger = new Map<any, keyof Registers>();
+	// Cleanups for things not held in the registry ledger (e.g. near-anchored
+	// buttons, which mount their own host). Run on dispose so nothing leaks
+	// when the module unloads.
+	private disposers = new Set<() => void>();
+
+	/**
+	 * Place a button in a known client location without touching register keys
+	 * or building the component yourself. Returns a handle to remove it early;
+	 * otherwise it is cleaned up when the module unloads.
+	 */
+	placeButton(location: ButtonLocation, options: PlaceButtonOptions): ButtonHandle {
+		const slot = BUTTON_SLOTS[location];
+		if (!slot) throw new Error(`[stdlib] unknown button location: ${location}`);
+		const [key, Component] = slot;
+		const element = React.createElement(Component as React.FC<PlaceButtonOptions>, { order: 0, ...options });
+
+		const inGroup = (): ButtonHandle => {
+			this.register(key, element);
+			return { remove: () => this.unregister(key, element) };
+		};
+
+		if (!options.near) return inGroup();
+		const { anchor, side = "after" } = options.near;
+		if (!isNativeAnchor(anchor)) {
+			warn(`[stdlib] unknown native anchor "${anchor}"; placing "${options.label}" with order instead`);
+			return inGroup();
+		}
+
+		// Try to sit next to the named native button; if it never appears, fall
+		// back to the module-button group so the button is never lost.
+		let fellBackHandle: ButtonHandle | undefined;
+		const adjacent = mountAdjacent({
+			className: "spicetify-near-button",
+			element,
+			findTarget: () => resolveNativeAnchor(anchor),
+			side,
+			giveUpMs: 5000,
+			onGiveUp: () => {
+				fellBackHandle ??= inGroup();
+			},
+		});
+		// Tracked so module unload (dispose) tears the near button down too; the
+		// near path never touches the registry ledger, so it needs its own hook.
+		const cleanup = () => {
+			adjacent.remove();
+			fellBackHandle?.remove();
+		};
+		this.disposers.add(cleanup);
+		return {
+			remove: () => {
+				this.disposers.delete(cleanup);
+				cleanup();
+			},
+		};
+	}
+
+	register<R extends keyof Registers>(type: R, ...args: Parameters<Registers[R]["add"]>) {
+		this.ledger.set(args[0], type);
+		// @ts-ignore
+		registers[type].add(...args);
+	}
+
+	// Routes are registered as elements with a string "route" tag; this
+	// hides that incantation. Returns the item for manual unregister.
+	registerRoute(path: string, element: React.ReactNode): React.ReactNode {
+		const item = React.createElement("route", { path, element });
+		this.register("route", item);
+		return item;
+	}
+
+	unregister<R extends keyof Registers>(type: R, ...args: Parameters<Registers[R]["delete"]>) {
+		this.ledger.delete(args[0]);
+		// @ts-ignore
+		registers[type].delete(...args);
+	}
+
+	dispose() {
+		for (const [item, type] of this.ledger.entries()) this.unregister(type, item);
+		this.ledger.clear();
+		for (const dispose of this.disposers) dispose();
+		this.disposers.clear();
+	}
+}
+
+export const createRegistrar = (ctx: ModuleRuntimeContext) => {
+	const registrar = new Registrar(ctx.identifier);
+	ctx.defer(() => {
+		registrar.dispose();
+	});
+	return registrar;
+};

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

@@ -0,0 +1,160 @@
+/*
+ * Copyright (C) 2024 Delusoire
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { React } from "../expose/React.ts";
+
+import { matchLast } from "../util.ts";
+
+import { warn } from "../logger.ts";
+import { transformer } from "../../mixin.ts";
+import { Registry } from "./registry.ts";
+
+type __MenuContext = React.Context<MenuContext>;
+
+declare global {
+	var __MenuContext: __MenuContext;
+}
+
+type MenuContext = {
+	props: any;
+	trigger: string;
+	target: HTMLElement;
+};
+
+const items = new Registry<React.ReactNode>();
+export default items;
+
+export const useMenuItem = () => React.useContext(globalThis.__MenuContext);
+
+declare global {
+	var __renderMenuItems: any;
+}
+
+globalThis.__renderMenuItems = () => items.all();
+transformer(
+	(emit) => (str) => {
+		emit();
+
+		str = str.replace(/("Menu".+?children:)([a-zA-Z_\$][\w\$]*)/, "$1[__renderMenuItems(),$2].flat()");
+
+		const croppedInput = str.match(/.*value:"contextmenu"/)![0];
+		const react = matchLast(croppedInput, /([a-zA-Z_\$][\w\$]*)\.useRef/g)[1];
+
+		const [, menu, trigger, target] =
+			matchLast(
+				croppedInput,
+				/\(\{[^}]*menu:([a-zA-Z_\$][\w\$]*),[^}]*trigger:([a-zA-Z_\$][\w\$]*),[^}]*triggerRef:([a-zA-Z_\$][\w\$]*)/g,
+			) ?? [];
+
+		let value: string;
+		if (menu && trigger && target) {
+			value = `{props:${menu}?.props,trigger:${trigger},target:${target}}`;
+		} else {
+			value = `{props:e.menu?.props,trigger:e.trigger,target:e.triggerRef}`;
+		}
+
+		str = str.replace(
+			/render:(.{0,100}?\(0,([a-zA-Z_\$][\w\$]*)\.jsx\)\([a-zA-Z_\$][\w\$]*\.[a-zA-Z_\$][\w\$]*,\{value:"contextmenu",[^\}]+\}[^,]+),/,
+			`render:(props)=>{const value=${value};return ($2.jsx)((globalThis.__MenuContext??=${react}.createContext(null)).Provider,{value,children:($1)(props)});},`,
+		);
+
+		return str;
+	},
+	{
+		glob: /^\/xpui\.js/,
+	},
+);
+
+// True when the open menu came from the profile (avatar) button. 1.2.94
+// dropped the user-widget-link testid; the account image inside the
+// trigger button is the durable discriminator, with the old testid kept
+// as a fallback for older clients.
+export const openedFromProfileMenu = (ctx: Pick<MenuContext, "trigger" | "target"> | null): boolean => {
+	if (!ctx || ctx.trigger !== "click") return false;
+	const button = ctx.target?.closest?.("button");
+	if (!button) return false;
+	return !!button.querySelector("img, figure") || button.getAttribute("data-testid") === "user-widget-link";
+};
+
+export const createProfileMenuShouldAdd = () => (ctx: MenuContext) => openedFromProfileMenu(ctx);
+
+// Foreign menu items have no access to the client's dismissal context;
+// the tippy portal only closes on an outside press. Call after handling
+// a click. Deferred so the item's own handler finishes first.
+export const closeMenu = (): void => {
+	setTimeout(() => {
+		document.body.dispatchEvent(new MouseEvent("mousedown", { bubbles: true }));
+	}, 0);
+};
+
+// Transform-free path: every context menu renders inside the #context-menu
+// tippy portal; registered items are appended to the menu list when one
+// opens. useMenuItem() carries the trigger and target captured from the
+// opening event — the menu component's own props are not reachable from
+// outside the client render pipeline and stay null.
+if (
+	!(globalThis as never as Record<string, unknown>).__SPICETIFY_APPLY_TRANSFORMS__ &&
+	typeof document !== "undefined"
+) {
+	void CHUNKS.xpui.promise.then(async () => {
+		const { ReactDOM } = await import("../expose/React.js");
+		const { createItemBoundary } = await import("./mount.js");
+		const R = React as any;
+		const createRoot = (ReactDOM as any).createRoot;
+		if (typeof createRoot !== "function") {
+			warn("[stdlib] cannot mount menu items (no createRoot)");
+			return;
+		}
+
+		let last: Omit<MenuContext, "props"> = { trigger: "", target: document.body } as never;
+		document.addEventListener(
+			"contextmenu",
+			(e) => {
+				last = { trigger: "right-click", target: e.target as HTMLElement };
+			},
+			true,
+		);
+		document.addEventListener(
+			"mousedown",
+			(e) => {
+				last = { trigger: "click", target: e.target as HTMLElement };
+			},
+			true,
+		);
+
+		const ItemBoundary = createItemBoundary(R, "menu");
+		const live: Array<{ menu: Element; root: { unmount: () => void } }> = [];
+		const processed = new WeakSet<Element>();
+
+		const sweep = () => {
+			for (let i = live.length - 1; i >= 0; i--) {
+				if (!live[i].menu.isConnected) {
+					live[i].root.unmount();
+					live.splice(i, 1);
+				}
+			}
+			if (items.size === 0) return;
+			for (const menu of document.querySelectorAll("#context-menu [role=menu]")) {
+				if (processed.has(menu)) continue;
+				processed.add(menu);
+				const host = document.createElement("li");
+				host.setAttribute("role", "presentation");
+				host.className = "spicetify-menu-items";
+				menu.appendChild(host);
+				const root = createRoot(host);
+				globalThis.__MenuContext ??= R.createContext(null);
+				root.render(
+					R.createElement(
+						globalThis.__MenuContext.Provider,
+						{ value: { props: null, ...last } },
+						...items.all().map((item, i) => R.createElement(ItemBoundary, { key: i }, item)),
+					),
+				);
+				live.push({ menu, root });
+			}
+		};
+		new MutationObserver(sweep).observe(document.body, { childList: true, subtree: true });
+	});
+}