@spicetify/kit 0.1.0 → 0.2.0

package/vendor/stdlib/lib/primitives.tsx

@@ -25,7 +25,12 @@ import {
 	SETTINGS_ROW_CLASS,
 	SETTINGS_ROW_CONTROL_CLASS,
 	SETTINGS_ROW_LABEL_CLASS,
+	SETTINGS_ROW_TEXT_CLASS,
+	SETTINGS_ACTION_GROUP_CLASS,
+	SETTINGS_HELP_TEXT_CLASS,
+	SETTINGS_LABEL_COPY_CLASS,
 	SETTINGS_SECTION_CLASS,
+	SETTINGS_SECTION_HEADING_CLASS,
 	badgeClass,
 	buttonClass,
 	type BadgeTone,
@@ -34,6 +39,7 @@ import {
 	chipClass,
 	DIALOG_BODY_CLASS,
 	DIALOG_CLASS,
+	DIALOG_LARGE_CLASS,
 	DIALOG_HEADER_CLASS,
 	ICON_BUTTON_CLASS,
 	MENU_ITEM_CLASS,
@@ -41,8 +47,11 @@ import {
 	SEARCHBAR_CLASS,
 	SELECT_CLASS,
 } from "./primitives-classes.ts";
+import { activateDialog } from "./dialog-lifecycle.ts";
+import { Tooltip } from "./floating.tsx";
 
 export type { BadgeTone, ButtonVariant } from "./primitives-classes.ts";
+export { Popover, PopoverMenu, PopoverMenuItem, Tooltip } from "./floating.tsx";
 
 // ---------- buttons ----------
 
@@ -75,15 +84,40 @@ export const IconButton: React.FC<{
 	</button>
 );
 
+// One shared ordering affordance for provider lists and other short ordered
+// settings. Keeping the arrows here prevents each module from inventing a
+// different size, icon, disabled state, or accessible label.
+export const ReorderButtons: React.FC<{
+	label: string;
+	disableUp: boolean;
+	disableDown: boolean;
+	onMove: (direction: -1 | 1) => void;
+}> = (props) => (
+	<span className={SETTINGS_ACTION_GROUP_CLASS}>
+		<IconButton ariaLabel={`Move ${props.label} up`} disabled={props.disableUp} onClick={() => props.onMove(-1)}>
+			↑
+		</IconButton>
+		<IconButton ariaLabel={`Move ${props.label} down`} disabled={props.disableDown} onClick={() => props.onMove(1)}>
+			↓
+		</IconButton>
+	</span>
+);
+
 // ---------- inputs ----------
 
 export function Select<T extends string>(props: {
 	options: ReadonlyArray<{ value: T; label: string }>;
 	value: T;
 	onChange: (value: T) => void;
+	ariaLabel?: string;
 }): React.ReactElement {
 	return (
-		<select className={SELECT_CLASS} value={props.value} onChange={(e) => props.onChange(e.target.value as T)}>
+		<select
+			className={SELECT_CLASS}
+			value={props.value}
+			aria-label={props.ariaLabel}
+			onChange={(e) => props.onChange(e.target.value as T)}
+		>
 			{props.options.map((option) => (
 				<option key={option.value} value={option.value}>
 					{option.label}
@@ -97,7 +131,11 @@ export const TextInput: React.FC<{
 	placeholder?: string;
 	value?: string;
 	disabled?: boolean;
+	readOnly?: boolean;
 	onInput?: (value: string) => void;
+	onFocus?: React.FocusEventHandler<HTMLInputElement>;
+	onBlur?: React.FocusEventHandler<HTMLInputElement>;
+	ariaLabel?: string;
 }> = (props) => (
 	<input
 		type="text"
@@ -105,6 +143,10 @@ export const TextInput: React.FC<{
 		placeholder={props.placeholder}
 		value={props.value}
 		disabled={props.disabled}
+		readOnly={props.readOnly}
+		aria-label={props.ariaLabel}
+		onFocus={props.onFocus}
+		onBlur={props.onBlur}
 		onChange={(e) => props.onInput?.(e.target.value)}
 	/>
 );
@@ -136,13 +178,12 @@ export const Card: React.FC<{ children: React.ReactNode }> = (props) => (
 
 // ---------- settings ----------
 
-// Native-looking settings chrome for the `settingsSection` register. These
-// render the client's own section/row structure rather than capturing its
-// components: the settings route is a lazily loaded chunk, and the loader
-// does not source-transform those, so a capture there never resolves.
+// Native-looking settings chrome for the `settingsSection` register on the
+// standalone Spicetify Settings page. These render the client's own section
+// and row structure rather than capturing its route-local components.
 export const SettingsSection: React.FC<{ title?: React.ReactNode; children: React.ReactNode }> = (props) => (
 	<div className={SETTINGS_SECTION_CLASS}>
-		{props.title === undefined ? null : <h2>{props.title}</h2>}
+		{props.title === undefined ? null : <h2 className={SETTINGS_SECTION_HEADING_CLASS}>{props.title}</h2>}
 		{props.children}
 	</div>
 );
@@ -155,18 +196,79 @@ export const SettingsRow: React.FC<{ label: React.ReactNode; htmlFor?: string; c
 ) => (
 	<div className={SETTINGS_ROW_CLASS}>
 		<div className={SETTINGS_ROW_LABEL_CLASS}>
-			{props.htmlFor === undefined ? props.label : <label htmlFor={props.htmlFor}>{props.label}</label>}
+			{props.htmlFor === undefined ? (
+				<span className={SETTINGS_ROW_TEXT_CLASS}>{props.label}</span>
+			) : (
+				<label className={SETTINGS_ROW_TEXT_CLASS} htmlFor={props.htmlFor}>
+					{props.label}
+				</label>
+			)}
 		</div>
 		<div className={SETTINGS_ROW_CONTROL_CLASS}>{props.children}</div>
 	</div>
 );
 
+export const SettingsLabel: React.FC<{ label: React.ReactNode; description?: React.ReactNode }> = (props) => (
+	<span className={SETTINGS_LABEL_COPY_CLASS}>
+		<span>{props.label}</span>
+		{props.description === undefined ? null : <span className={SETTINGS_HELP_TEXT_CLASS}>{props.description}</span>}
+	</span>
+);
+
+export const SettingsActions: React.FC<{ children: React.ReactNode }> = (props) => (
+	<span className={SETTINGS_ACTION_GROUP_CLASS}>{props.children}</span>
+);
+
+export const SettingsButtonRow: React.FC<{
+	label: React.ReactNode;
+	description?: React.ReactNode;
+	buttonLabel: React.ReactNode;
+	disabled?: boolean;
+	variant?: ButtonVariant;
+	onClick: () => void;
+}> = (props) => (
+	<SettingsRow label={<SettingsLabel label={props.label} description={props.description} />}>
+		<Button variant={props.variant ?? "secondary"} disabled={props.disabled} onClick={props.onClick}>
+			{props.buttonLabel}
+		</Button>
+	</SettingsRow>
+);
+
+export const SettingsTextInputRow: React.FC<{
+	label: React.ReactNode;
+	description?: React.ReactNode;
+	value: string;
+	placeholder?: string;
+	ariaLabel?: string;
+	onInput: (value: string) => void;
+	actionLabel?: React.ReactNode;
+	actionDisabled?: boolean;
+	onAction?: () => void;
+}> = (props) => (
+	<SettingsRow label={<SettingsLabel label={props.label} description={props.description} />}>
+		<SettingsActions>
+			<TextInput
+				value={props.value}
+				placeholder={props.placeholder}
+				ariaLabel={props.ariaLabel}
+				onInput={props.onInput}
+			/>
+			{props.actionLabel === undefined || props.onAction === undefined ? null : (
+				<Button variant="secondary" disabled={props.actionDisabled} onClick={props.onAction}>
+					{props.actionLabel}
+				</Button>
+			)}
+		</SettingsActions>
+	</SettingsRow>
+);
+
 // The client's own switch structure around a native checkbox. Its semantic
 // classes are recreated by the CLI css-map, so Spotify and themes style this
 // exactly like the adjacent settings controls.
 export const Toggle: React.FC<{
 	id?: string;
 	ariaLabel?: string;
+	disabled?: boolean;
 	value: boolean;
 	onChange: (value: boolean) => void;
 }> = (props) => (
@@ -177,6 +279,7 @@ export const Toggle: React.FC<{
 			id={props.id}
 			aria-label={props.ariaLabel}
 			checked={props.value}
+			disabled={props.disabled}
 			onKeyDown={activateToggleOnKeyDown}
 			onChange={(e) => props.onChange((e.target as HTMLInputElement).checked)}
 		/>
@@ -186,6 +289,46 @@ export const Toggle: React.FC<{
 	</label>
 );
 
+export const SettingsProviderRow: React.FC<{
+	label: string;
+	description?: React.ReactNode;
+	value: boolean;
+	disabled?: boolean;
+	disabledReason?: string;
+	index: number;
+	total: number;
+	onChange: (value: boolean) => void;
+	onMove: (direction: -1 | 1) => void;
+}> = (props) => {
+	const id = React.useId();
+	const toggle = (
+		<Toggle
+			id={id}
+			ariaLabel={`${props.label} provider`}
+			value={props.value}
+			disabled={props.disabled}
+			onChange={props.onChange}
+		/>
+	);
+	return (
+		<SettingsRow label={<SettingsLabel label={props.label} description={props.description} />} htmlFor={id}>
+			<SettingsActions>
+				<ReorderButtons
+					label={props.label}
+					disableUp={props.index === 0}
+					disableDown={props.index === props.total - 1}
+					onMove={props.onMove}
+				/>
+				{props.disabled && props.disabledReason ? (
+					<Tooltip label={props.disabledReason}>{toggle}</Tooltip>
+				) : (
+					toggle
+				)}
+			</SettingsActions>
+		</SettingsRow>
+	);
+};
+
 // The "module with one boolean setting" pattern as a single row for the
 // `settingsRow` register. `getValue` is read lazily on every mount so
 // reopening settings always reflects the current state; the element itself
@@ -275,34 +418,41 @@ export const ConfirmButton: React.FC<{
 // transformed ancestor (the norm for Spotify's scroll containers) would
 // otherwise be clipped/offset to that ancestor. The backdrop and the ×
 // button both call onClose.
-export const Dialog: React.FC<{ title: string; onClose: () => void; children: React.ReactNode }> = (props) => {
-	const { onClose } = props;
-	// Escape closes the dialog, matching every native modal. A capturing
-	// document listener catches the key wherever focus sits (the client's own
-	// components steal focus), and the client's shortcut handlers do not see it.
+export const Dialog: React.FC<{
+	title: string;
+	onClose: () => void;
+	size?: "normal" | "large";
+	children: React.ReactNode;
+}> = (props) => {
+	const dialogRef = React.useRef<HTMLDivElement>(null);
+	const onCloseRef = React.useRef(props.onClose);
+	const titleId = React.useId();
+	onCloseRef.current = props.onClose;
 	React.useEffect(() => {
-		const onKey = (e: KeyboardEvent) => {
-			if (e.key === "Escape") {
-				e.preventDefault();
-				e.stopPropagation();
-				onClose();
-			}
-		};
-		document.addEventListener("keydown", onKey, true);
-		return () => document.removeEventListener("keydown", onKey, true);
-	}, [onClose]);
+		const dialog = dialogRef.current;
+		if (!dialog) return;
+		return activateDialog(dialog, () => onCloseRef.current());
+	}, []);
+	const dialogClass = props.size === "large" ? `${DIALOG_CLASS} ${DIALOG_LARGE_CLASS}` : DIALOG_CLASS;
 
 	return ReactDOM.createPortal(
 		<div
 			className={SCRIM_CLASS}
 			onClick={(e) => {
-				if (e.target === e.currentTarget) onClose();
+				if (e.target === e.currentTarget) props.onClose();
 			}}
 		>
-			<div className={DIALOG_CLASS} role="dialog" aria-modal="true" aria-label={props.title}>
+			<div
+				ref={dialogRef}
+				className={dialogClass}
+				role="dialog"
+				aria-modal="true"
+				aria-labelledby={titleId}
+				tabIndex={-1}
+			>
 				<div className={DIALOG_HEADER_CLASS}>
-					<h2>{props.title}</h2>
-					<IconButton ariaLabel="Close" onClick={onClose}>
+					<h2 id={titleId}>{props.title}</h2>
+					<IconButton ariaLabel="Close" onClick={props.onClose}>
 						×
 					</IconButton>
 				</div>

package/vendor/stdlib/metadata.json

@@ -3,7 +3,7 @@
 	"kind": "lib",
 	"hidden": true,
 	"preview": "./assets/PREVIEW.png",
-	"version": "1.5.0",
+	"version": "1.10.0",
 	"compat": ["0.3.0"],
 	"authors": ["spicetify", "Delusoire"],
 	"description": "The standard library",

package/vendor/stdlib/mod.ts

@@ -18,9 +18,12 @@ export * from "./lib/primitives-vanilla.ts";
 export * from "./src/storage.ts";
 export * from "./src/wpunpk.ts";
 export * from "./src/logger.ts";
+export { display as displayModal, hide as hideModal, type ModalOptions } from "./lib/modal.tsx";
+export { React, ReactDOM, ReactDOMServer } from "./src/expose/React.ts";
+export { Platform } from "./src/expose/Platform.ts";
+export { createIconComponent } from "./src/createIconComponent.tsx";
+export { startCase } from "./deps.ts";
 
-// Public barrel: everything dependent modules are allowed to deep-import.
-// Import from /modules/stdlib/mod.js at runtime; nothing else is public.
-export * from "./src/webpack/misc.xpui.ts";
-export * from "./src/webpack/ComponentLibrary.xpui.ts";
-export * from "./src/webpack/ReactComponents.xpui.ts";
+// Palette Manager needs the client's Color constructor and its companion
+// type. Export that semantic capability without exposing the webpack module.
+export { Color } from "./src/webpack/misc.xpui.ts";

package/vendor/stdlib/src/client.ts

@@ -13,10 +13,28 @@
  * modules.
  */
 
+import type { ModalOptions } from "../lib/modal.tsx";
+
 type SpicetifyRuntime = typeof Spicetify;
 
 export type PlayerState = Spicetify.PlayerState;
 
+export interface PopupModalCompatibility {
+	display(options: ModalOptions): void;
+	hide(): void;
+}
+
+export interface DaemonCapabilities {
+	available(): Promise<boolean>;
+	apply(): Promise<unknown>;
+	blockUpdates(): Promise<unknown>;
+	unblockUpdates(): Promise<unknown>;
+}
+
+export interface SnackbarCapabilities {
+	enqueueSnackbar(message: string, options?: { variant?: string }): unknown;
+}
+
 export interface ClientCapabilities {
 	readonly player: typeof Spicetify.Player;
 	readonly platform: typeof Spicetify.Platform;
@@ -30,9 +48,14 @@ export interface ClientCapabilities {
 	readonly keyboard: typeof Spicetify.Keyboard;
 	readonly mousetrap: typeof Spicetify.Mousetrap;
 	readonly contextMenu: typeof Spicetify.ContextMenu;
-	readonly popupModal: typeof Spicetify.PopupModal;
+	/** @deprecated Import displayModal and hideModal from /modules/stdlib/mod.ts. */
+	readonly popupModal: PopupModalCompatibility;
 	readonly config: typeof Spicetify.Config;
 	readonly modules: typeof Spicetify.Modules;
+	/** V3 manifest version, with the legacy wrapper config as a fallback. */
+	readonly spicetifyVersion: string | undefined;
+	readonly daemon: DaemonCapabilities | undefined;
+	readonly snackbar: SnackbarCapabilities | undefined;
 	readonly react: typeof Spicetify.React;
 	readonly reactDOM: typeof Spicetify.ReactDOM;
 	readonly tippy: typeof Spicetify.Tippy;
@@ -47,6 +70,26 @@ const runtime = (): SpicetifyRuntime => {
 	return value;
 };
 
+const nonEmptyVersion = (value: unknown): string | undefined =>
+	typeof value === "string" && value.trim() ? value : undefined;
+
+let modalRequestGeneration = 0;
+const reportModalFailure = (error: unknown) => console.error("[stdlib] failed to load the owned modal:", error);
+const popupModalCompatibility: PopupModalCompatibility = {
+	display(options) {
+		const generation = ++modalRequestGeneration;
+		void import("../lib/modal.tsx")
+			.then(({ display }) => {
+				if (generation === modalRequestGeneration) display(options);
+			})
+			.catch(reportModalFailure);
+	},
+	hide() {
+		++modalRequestGeneration;
+		void import("../lib/modal.tsx").then(({ hide }) => hide()).catch(reportModalFailure);
+	},
+};
+
 export const client: ClientCapabilities = {
 	get player() {
 		return runtime().Player;
@@ -85,7 +128,7 @@ export const client: ClientCapabilities = {
 		return runtime().ContextMenu;
 	},
 	get popupModal() {
-		return runtime().PopupModal;
+		return popupModalCompatibility;
 	},
 	get config() {
 		return runtime().Config;
@@ -93,6 +136,26 @@ export const client: ClientCapabilities = {
 	get modules() {
 		return runtime().Modules;
 	},
+	get spicetifyVersion() {
+		const current = runtime() as unknown as {
+			Modules?: {
+				manifest?: { cliVersion?: unknown };
+				registry?: { manifest?: { cliVersion?: unknown } };
+			};
+			Config?: { version?: unknown };
+		};
+		return (
+			nonEmptyVersion(current.Modules?.manifest?.cliVersion) ??
+			nonEmptyVersion(current.Modules?.registry?.manifest?.cliVersion) ??
+			nonEmptyVersion(current.Config?.version)
+		);
+	},
+	get daemon() {
+		return (runtime() as unknown as { Daemon?: DaemonCapabilities }).Daemon;
+	},
+	get snackbar() {
+		return (runtime() as unknown as { Snackbar?: SnackbarCapabilities }).Snackbar;
+	},
 	get react() {
 		return runtime().React;
 	},

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