@unbound-app/api 0.11.0 → 1.1.0

package/src/utils/index.d.ts

@@ -0,0 +1,53 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+import type { PredicateResult } from '../_types';
+import * as React$1 from 'react';
+import { ReactElement } from 'react';
+/**
+ * @description Finds every node in an object graph a predicate matches, depth-first from the root. Cycle-safe.
+ * @template T The matched nodes' type.
+ * @param root The node to start from; it is tested too.
+ * @param predicate Tests each non-nullish node.
+ * @param options Which keys to descend into or skip, and how deep.
+ * @returns Every match, in visiting order.
+ */
+export declare function filterInTree<T = TreeNode>(
+	root: TreeNode,
+	predicate: TreePredicate,
+	options?: TreeSearchOptions,
+): T[];
+/**
+ * @description Finds the first node in an object graph a predicate matches, depth-first from the root. Cycle-safe.
+ * @template T The matched node's type.
+ * @param root The node to start from; it is tested too.
+ * @param predicate Tests each non-nullish node.
+ * @param options Which keys to descend into or skip, and how deep.
+ * @returns The first match, or `undefined` when none matches.
+ */
+export declare function findInTree<T = TreeNode>(
+	root: TreeNode,
+	predicate: TreePredicate,
+	options?: TreeSearchOptions,
+): T | undefined;
+/**
+ * Picks an element: a component name, matched against its `displayName` or `name` through `memo` and `forwardRef`
+ * wrappers (or a host type such as `RCTView`), or a predicate on the element.
+ * @template P The element's props.
+ */
+export type ComponentMatch<P = TreeNode> =
+	| string
+	| ((element: React$1.ReactElement<P>) => PredicateResult);
+/** A node in an object graph, such as a React tree. Discord's trees carry no static types, so a predicate reads them unchecked. */
+export type TreeNode = any;
+/** Tests one node of a tree; a truthy result is a match. */
+export type TreePredicate = (node: TreeNode) => PredicateResult;
+/** How a tree search descends. */
+export type TreeSearchOptions = {
+	/** The only keys descended into; every own key when omitted. Array items are always walked. */
+	walkable?: string[];
+	/** Keys never descended into. */
+	ignore?: string[];
+	/** How many levels below the root to descend. Defaults to 100. */
+	maxDepth?: number;
+};
+export * as react from './react/index';

package/src/utils/react/index.d.ts

@@ -0,0 +1,82 @@
+// Auto-generated by generate-plugin-sdk.ts - DO NOT EDIT
+
+import type { PredicateResult } from '../../_types';
+import * as React$1 from 'react';
+import { ReactElement } from 'react';
+
+/** Compares two values one level deep: each own key, or each entry of a Map, Set or array, by `Object.is`. Pass it as `isEqual`. */
+export declare const shallow: <T>(previous: T, next: T) => boolean;
+/** Wraps a selector so a result shallow-equal to its last one returns the last one, which skips the re-render. */
+export declare const useShallow: <S, U>(selector: (state: S) => U) => (state: S) => U;
+/**
+ * @description Finds every element in a rendered tree that a component name or predicate picks, walking only `props` and `children`.
+ * @template P The elements' props.
+ * @param tree A render result, such as `result` in an `after` patch.
+ * @param match A component name, or a predicate on each element.
+ * @returns Every matching element, outermost first.
+ */
+export declare function filterComponents<P = TreeNode>(
+	tree: TreeNode,
+	match: ComponentMatch<P>,
+): React$1.ReactElement<P>[];
+/**
+ * @description Finds every node in a React element or fiber tree a predicate matches, searching only downward.
+ * Start from an element, a fiber, or a class instance's `_reactInternals`.
+ * @template T The matched nodes' type.
+ * @param root The element or fiber to start from; it is tested too.
+ * @param predicate Tests each non-nullish node.
+ * @param options `walkable` adds keys to the React ones (such as `return`), `ignore` skips keys, `maxDepth` defaults to 100.
+ * @returns Every match, in visiting order.
+ */
+export declare function filterInTree<T = TreeNode>(
+	root: TreeNode,
+	predicate: TreePredicate,
+	options?: TreeSearchOptions,
+): T[];
+/**
+ * @description Finds the first element in a rendered tree that a component name or predicate picks, walking only `props` and `children`.
+ * @template P The element's props.
+ * @param tree A render result, such as `result` in an `after` patch.
+ * @param match A component name, or a predicate on each element.
+ * @returns The first matching element, or `undefined` when none matches.
+ */
+export declare function findComponent<P = TreeNode>(
+	tree: TreeNode,
+	match: ComponentMatch<P>,
+): React$1.ReactElement<P> | undefined;
+/**
+ * @description Finds the first node in a React element or fiber tree a predicate matches, searching only downward.
+ * Start from an element, a fiber, or a class instance's `_reactInternals`.
+ * @template T The matched node's type.
+ * @param root The element or fiber to start from; it is tested too.
+ * @param predicate Tests each non-nullish node.
+ * @param options `walkable` adds keys to the React ones (such as `return`), `ignore` skips keys, `maxDepth` defaults to 100.
+ * @returns The first match, or `undefined` when none matches.
+ */
+export declare function findInTree<T = TreeNode>(
+	root: TreeNode,
+	predicate: TreePredicate,
+	options?: TreeSearchOptions,
+): T | undefined;
+/**
+ * Picks an element: a component name, matched against its `displayName` or `name` through `memo` and `forwardRef`
+ * wrappers (or a host type such as `RCTView`), or a predicate on the element.
+ * @template P The element's props.
+ */
+export type ComponentMatch<P = TreeNode> =
+	| string
+	| ((element: React$1.ReactElement<P>) => PredicateResult);
+/** A node in an object graph, such as a React tree. Discord's trees carry no static types, so a predicate reads them unchecked. */
+export type TreeNode = any;
+/** Tests one node of a tree; a truthy result is a match. */
+export type TreePredicate = (node: TreeNode) => PredicateResult;
+/** How a tree search descends. */
+export type TreeSearchOptions = {
+	/** The only keys descended into; every own key when omitted. Array items are always walked. */
+	walkable?: string[];
+	/** Keys never descended into. */
+	ignore?: string[];
+	/** How many levels below the root to descend. Defaults to 100. */
+	maxDepth?: number;
+};
+export {};

package/testing/fake-api.ts

@@ -0,0 +1,256 @@
+import { useEffect, useState } from 'react';
+
+import type { ListenerRegistry } from './listener-registry';
+import type { FluxAction, FluxStore } from '../src/flux';
+import type { FakeModule } from './fake-metro';
+
+/** A seeded store's methods and fields, whatever the test gives it, such as `getCurrentUser`. */
+type StoreSeed = FakeModule;
+
+/** The Flux stores to seed, by name with or without `Store`, such as `{ User: { getCurrentUser: () => user } }`. */
+export type StoreSeeds = Record<string, StoreSeed>;
+
+/** The fake `flux`: stores the test seeds, and a dispatcher that records each action. */
+export type FakeFlux = {
+	/** Every action `dispatch` sent, in order. */
+	dispatched: FluxAction[];
+	/** Adds stores, or replaces a seeded store's methods and emits its change; `getStore` reads them on each access. */
+	seed: (stores: StoreSeeds) => void;
+	/** Calls a seeded store's change listeners, re-rendering each `useStore` reading it. */
+	emit: (name: string) => void;
+	getStore: (name: string) => FluxStore & StoreSeed;
+	/** The seeded stores that have a change listener added with `addChangeListener` rather than `onStoreChange`, which Unbound does not remove when a plugin stops. */
+	directListeners: () => string[];
+	/** Reads `selector(stores)` on each render, and re-renders when a store emits; `deps` and `isEqual` change nothing a test sees. */
+	useStore: <S extends FluxStore | readonly FluxStore[], T>(
+		stores: S,
+		selector: (stores: S) => T,
+	) => T;
+	onStoreChange: (store: FluxStore, listener: () => void) => () => void;
+	onAction: (type: string, listener: (action: FluxAction) => void) => () => void;
+	interceptAction: (
+		type: string,
+		interceptor: (action: FluxAction) => boolean | void,
+	) => () => void;
+	dispatch: (action: FluxAction) => Promise<void>;
+	reset: () => void;
+};
+
+/** The fake `assets`: every name has a stable id, so an image import equals `assets.getIdByName(name)`. */
+export type FakeAssets = {
+	getIdByName: (name: string, type?: AssetType) => number;
+	getByName: (name: string, type?: AssetType) => FakeAsset;
+	register: (options: AssetRegistration) => RegisteredAsset;
+	onAssetRegistered: (listener: AssetListener) => () => void;
+};
+
+/** The type an asset is asked for by. */
+export type AssetType = 'svg' | 'png';
+
+/** An asset `getByName` returns. */
+export type FakeAsset = { id: number; name: string; type: string };
+
+/** What `register` takes: the asset's name, and its type. */
+export type AssetRegistration = { name: string; type?: string };
+
+/** What `register` returns: the asset's id, and how to take it out again. */
+export type RegisteredAsset = { id: number; unregister: () => void };
+
+/** Called with each asset registered, and its id. */
+export type AssetListener = (asset: AssetRegistration, id: number) => void;
+
+/**
+ * @description Gives an asset name a stable fake id, the same in every run.
+ * @param name The asset's name, such as `icon` for `assets/icon.png`.
+ * @param type The type it was asked for; an SVG's `?asset` raster asks for `png`.
+ * @returns A positive id.
+ */
+export function fakeAssetId(name: string, type: string = ''): number {
+	let hash = 0x811c9dc5;
+
+	for (const char of `${type}:${name}`) {
+		hash = Math.imul(hash ^ (char.codePointAt(0) ?? 0), 0x01000193);
+	}
+
+	return 1000 + ((hash >>> 0) % 1_000_000);
+}
+
+function shortName(name: string): string {
+	return name.endsWith('Store') ? name.slice(0, -'Store'.length) : name;
+}
+
+/**
+ * @description Creates the fake `flux`, whose listeners go through `listeners` so `stopPlugin` sees any left behind.
+ * @param listeners The registry the plugin's listeners are tracked in.
+ * @returns The flux.
+ */
+export function createFakeFlux(listeners: ListenerRegistry): FakeFlux {
+	const stores = new Map<string, FluxStore & StoreSeed>();
+	const actionListeners = new Map<string, Set<(action: FluxAction) => void>>();
+	const interceptors = new Map<string, Set<(action: FluxAction) => boolean | void>>();
+	const dispatched: FluxAction[] = [];
+	const direct = new Map<() => void, string>();
+	let internal = 0;
+
+	// The kit's own subscriptions (`useStore`, `onStoreChange`) go through here, so only a plugin's own count as direct.
+	function subscribed<T>(run: () => T): T {
+		internal++;
+
+		try {
+			return run();
+		} finally {
+			internal--;
+		}
+	}
+
+	function storeOf(name: string, seed: StoreSeed): FluxStore & StoreSeed {
+		const changeListeners = new Set<() => void>();
+
+		return {
+			getName: () => `${name}Store`,
+			addChangeListener(listener) {
+				changeListeners.add(listener);
+
+				if (internal === 0) {
+					direct.set(listener, `${name}Store.addChangeListener`);
+				}
+			},
+			removeChangeListener(listener) {
+				changeListeners.delete(listener);
+				direct.delete(listener);
+			},
+			emitChange: () => {
+				for (const listener of changeListeners) listener();
+			},
+			...seed,
+		};
+	}
+
+	function seeded(name: string) {
+		const store = stores.get(shortName(name));
+
+		if (!store) {
+			throw new Error(
+				`Failed to read Flux store ${name}: seed it with render(..., { stores: { ${shortName(name)}: {...} } }).`,
+			);
+		}
+
+		return store;
+	}
+
+	function subscribe<T>(map: Map<string, Set<T>>, type: string, listener: T, label: string) {
+		const set = map.get(type) ?? new Set<T>();
+
+		map.set(type, set);
+		set.add(listener);
+
+		return listeners.track(label, () => void set.delete(listener));
+	}
+
+	return {
+		dispatched,
+		seed(next) {
+			for (const [name, seed] of Object.entries(next)) {
+				const existing = stores.get(shortName(name));
+
+				// The same object keeps its change listeners, so a `useStore` reading it re-renders.
+				if (existing) {
+					Object.assign(existing, seed);
+					existing.emitChange();
+				} else {
+					stores.set(shortName(name), storeOf(shortName(name), seed));
+				}
+			}
+		},
+		emit: (name) => seeded(name).emitChange(),
+		// Lazy, as on device: a store read at import resolves on first property access.
+		// Every operation lands on the seeded store, so a patch made through the proxy shows in later reads.
+		getStore: (name) =>
+			new Proxy<FluxStore & StoreSeed>(storeOf(shortName(name), {}), {
+				get: (_target, key) => Reflect.get(seeded(name), key),
+				set: (_target, key, value) => Reflect.set(seeded(name), key, value),
+				has: (_target, key) => key in seeded(name),
+				deleteProperty: (_target, key) => Reflect.deleteProperty(seeded(name), key),
+				defineProperty: (_target, key, descriptor) =>
+					Reflect.defineProperty(seeded(name), key, descriptor),
+			}),
+		directListeners: () => [...direct.values()],
+		useStore(watched, selector) {
+			const [, forceUpdate] = useState({});
+			const list = [watched].flat();
+
+			useEffect(() => {
+				const update = () => forceUpdate({});
+
+				subscribed(() => {
+					for (const store of list) store.addChangeListener(update);
+				});
+
+				return () => {
+					for (const store of list) store.removeChangeListener(update);
+				};
+			}, list);
+
+			return selector(watched);
+		},
+		onStoreChange(store, listener) {
+			subscribed(() => store.addChangeListener(listener));
+
+			return listeners.track(`flux.onStoreChange(${store.getName()})`, () =>
+				store.removeChangeListener(listener),
+			);
+		},
+		onAction: (type, listener) =>
+			subscribe(actionListeners, type, listener, `flux.onAction(${type})`),
+		interceptAction: (type, interceptor) =>
+			subscribe(interceptors, type, interceptor, `flux.interceptAction(${type})`),
+		async dispatch(action) {
+			dispatched.push(action);
+
+			for (const interceptor of interceptors.get(action.type) ?? []) {
+				if (interceptor(action) === true) return;
+			}
+
+			for (const listener of actionListeners.get(action.type) ?? []) listener(action);
+		},
+		reset() {
+			stores.clear();
+			direct.clear();
+			actionListeners.clear();
+			interceptors.clear();
+			dispatched.length = 0;
+		},
+	};
+}
+
+/**
+ * @description Creates the fake `assets`.
+ * @param listeners The registry registrations and listeners are tracked in.
+ * @returns The assets.
+ */
+export function createFakeAssets(listeners: ListenerRegistry): FakeAssets {
+	const registered = new Set<AssetListener>();
+
+	return {
+		getIdByName: (name, type) => fakeAssetId(name, type),
+		getByName: (name, type) => ({ id: fakeAssetId(name, type), name, type: type ?? 'png' }),
+		register(options) {
+			const id = fakeAssetId(options.name, options.type);
+
+			for (const listener of registered) listener(options, id);
+
+			return {
+				id,
+				unregister: listeners.track(`assets.register(${options.name})`, () => {}),
+			};
+		},
+		onAssetRegistered(listener) {
+			registered.add(listener);
+
+			return listeners.track(
+				'assets.onAssetRegistered',
+				() => void registered.delete(listener),
+			);
+		},
+	};
+}

package/testing/fake-components.ts

@@ -0,0 +1,183 @@
+import type { ReactNode } from 'react';
+
+import type { FakeModule } from './fake-metro';
+
+type ComponentProps = { children?: ReactNode } & FakeModule;
+
+/** A fake Discord component: it draws its children, and the text prop of a button or row, and `find` reaches it by the name it was made with. */
+export type FakeComponent = ((props: ComponentProps) => ReactNode) & FakeModule;
+
+const BAGS = [
+	'AvatarPiles',
+	'Avatars',
+	'BackdropFilters',
+	'BottomSheets',
+	'DefaultAvatars',
+	'Discord',
+	'FlashList',
+	'Forms',
+	'Media',
+	'Portal',
+	'SafeArea',
+	'Video',
+] as const;
+
+const UI = [
+	'ButtonRow',
+	'CheckboxRow',
+	'ChecklistRow',
+	'ColorRow',
+	'DurationRow',
+	'EntityRow',
+	'InputRow',
+	'ListRow',
+	'MultilineRow',
+	'NumberRow',
+	'Page',
+	'PaletteRow',
+	'PickerRow',
+	'RadioRow',
+	'ResetRow',
+	'RestartRow',
+	'Row',
+	'SchemaPanel',
+	'SecretRow',
+	'Section',
+	'SegmentedRow',
+	'SliderRow',
+	'StepperRow',
+	'SwitchRow',
+	'UrlRow',
+] as const;
+
+// The components that draw a string prop as their text on device, so `text()` and `find` see it.
+const TEXT_PROPS: Record<string, string[]> = {
+	Button: ['text'],
+	RowButton: ['label', 'subLabel'],
+	TableRow: ['label', 'subLabel'],
+	TableRadioRow: ['label', 'subLabel'],
+	TableSwitchRow: ['label', 'subLabel'],
+	TableCheckboxRow: ['label', 'subLabel'],
+};
+
+function isCapitalised(key: string): boolean {
+	return key !== '' && key[0] === key[0]?.toUpperCase() && key[0] !== key[0]?.toLowerCase();
+}
+
+/**
+ * @description Creates a component that draws its children and is named `name`, so `find(name)` reaches it with its props.
+ * A capitalised member, such as `ActionSheetRow.Icon`, is another component named `ActionSheetRow.Icon`.
+ * @param name The name `find` matches.
+ * @returns The component.
+ */
+export function createFakeComponent(name: string): FakeComponent {
+	const members = new Map<string, FakeComponent>();
+
+	const textProps = TEXT_PROPS[name] ?? [];
+
+	function Component(props: ComponentProps): ReactNode {
+		const drawn = textProps.map((key) => props[key]).filter((text) => typeof text === 'string');
+
+		return drawn.length ? [...drawn, props.children] : (props.children ?? null);
+	}
+
+	Component.displayName = name;
+
+	return new Proxy(Component as FakeComponent, {
+		get(target, key, receiver) {
+			if (typeof key !== 'string' || key in target || !isCapitalised(key)) {
+				return Reflect.get(target, key, receiver);
+			}
+
+			const member = members.get(key) ?? createFakeComponent(`${name}.${key}`);
+
+			members.set(key, member);
+
+			return member;
+		},
+	});
+}
+
+/**
+ * @description Creates a module of fake components: any capitalised name is a component of that name, and a test may set its own.
+ * @param members Members that are not components, such as `createStyles`.
+ * @returns The module.
+ */
+function createComponentBag(members: FakeModule = {}): FakeModule {
+	const components = new Map<string, unknown>(Object.entries(members));
+
+	return new Proxy<FakeModule>(
+		{},
+		{
+			get(_target, key) {
+				if (typeof key !== 'string') {
+					return undefined;
+				}
+
+				if (!isCapitalised(key)) {
+					return components.get(key);
+				}
+
+				const component = components.get(key) ?? createFakeComponent(key);
+
+				components.set(key, component);
+
+				return component;
+			},
+			set(_target, key, value) {
+				if (typeof key === 'string') {
+					components.set(key, value);
+				}
+
+				return true;
+			},
+			has: (_target, key) =>
+				typeof key === 'string' && (isCapitalised(key) || components.has(key)),
+		},
+	);
+}
+
+// `createStyles` of Discord's design module returns a hook of the styles; a factory is called with no theme.
+function createStyles<T>(styles: T | (() => T)): () => T {
+	return () => (typeof styles === 'function' ? (styles as () => T)() : styles);
+}
+
+/**
+ * @description Creates the fake `metro.components`: each module a bag of fake components, so `Discord.Text` and `BottomSheets.ActionSheet`
+ * render as nodes named after themselves, with `Discord.createStyles` returning the styles it is given.
+ * @returns The namespace.
+ */
+export function createFakeComponents(): FakeModule {
+	const bags = Object.fromEntries(BAGS.map((name) => [name, createComponentBag()]));
+
+	return {
+		...bags,
+		Discord: createComponentBag({ createStyles }),
+		HelpMessage: createFakeComponent('HelpMessage'),
+		Switch: createFakeComponent('Switch'),
+		HelpMessageTypes: {
+			0: 'WARNING',
+			1: 'INFO',
+			2: 'ERROR',
+			3: 'SUCCESS',
+			WARNING: 0,
+			INFO: 1,
+			ERROR: 2,
+			SUCCESS: 3,
+		},
+		DESIGN_COMPONENTS: [],
+		// UNKNOWN: any value may be tested for being renderable.
+		isRenderable: (value: unknown) =>
+			typeof value === 'function' ||
+			(typeof value === 'object' && value !== null && '$$typeof' in value),
+		registerDesignFallback: () => {},
+	};
+}
+
+/**
+ * @description Creates the fake `ui`: each settings row and layout component draws its children and is named after itself.
+ * @returns The namespace.
+ */
+export function createFakeUi(): FakeModule {
+	return Object.fromEntries(UI.map((name) => [name, createFakeComponent(name)]));
+}