@unbound-app/api 0.9.0 → 1.1.0

package/testing/fake-settings-panel.ts

@@ -0,0 +1,173 @@
+import { createElement, type ReactElement } from 'react';
+
+import type { SchemaNode, SettingsSchema, SettingsValues, SettingValue } from './fake-settings';
+
+/** What the generated panel needs from the fake settings it is drawn for. */
+export type PanelSource = {
+	schema: SettingsSchema;
+	/** The settings as `settings.ts` predicates read them, defaults applied. */
+	values: SettingsValues;
+	/** Reads a stored setting by dot-separated key. */
+	read: (key: string) => SettingValue | SettingsValues;
+	/** Saves a setting by dot-separated key. */
+	write: (key: string, value: SettingValue) => void;
+	/** Re-renders the panel when any setting changes. */
+	useChange: () => void;
+	/** Looks a message key up in the active locale, re-rendering when it changes. */
+	translate: (key: string) => string;
+	/** Runs the export of src/actions.ts a button names. */
+	runAction: (name: string) => Promise<void>;
+};
+
+type Condition = string | { predicate: true; run?: (settings: SettingsValues) => boolean };
+
+const ROWS: Record<string, string> = {
+	'boolean:switch': 'SwitchRow',
+	'boolean:checkbox': 'CheckboxRow',
+	'integer:input': 'NumberRow',
+	'integer:slider': 'SliderRow',
+	'integer:stepper': 'StepperRow',
+	'integer:duration': 'DurationRow',
+	'string:input': 'InputRow',
+	'string:multiline': 'MultilineRow',
+	'string:secret': 'SecretRow',
+	'string:url': 'UrlRow',
+	'string:color': 'ColorRow',
+	'choice:radio': 'RadioRow',
+	'choice:picker': 'PickerRow',
+	'choice:segmented': 'SegmentedRow',
+	'array:list': 'ListRow',
+	'array:checkboxes': 'ChecklistRow',
+	button: 'ButtonRow',
+	notice: 'NoticeRow',
+};
+
+// `number` shares the integer rows, and each entity display is an entity row.
+function rowName(node: SchemaNode): string {
+	const kind = node.kind === 'number' ? 'integer' : node.kind;
+	const display = String(node.displayAs);
+	const entity = ['user', 'channel', 'guild', 'role'].includes(display);
+
+	if (display === 'color' && node.palette === true) {
+		return 'PaletteRow';
+	}
+
+	return (
+		ROWS[kind] ??
+		ROWS[`${kind}:${display}`] ??
+		(entity ? 'EntityRow' : `${display[0]?.toUpperCase()}${display.slice(1)}Row`)
+	);
+}
+
+// Mirrors the client's `evaluateCondition`: a boolean setting's key, or the predicate the build lifted out of settings.ts.
+function holds(source: PanelSource, condition: Condition | undefined): boolean | undefined {
+	if (condition === undefined) return;
+
+	if (typeof condition === 'string') {
+		return source.read(condition) === true;
+	}
+
+	return condition.run ? Boolean(condition.run(source.values)) : undefined;
+}
+
+function row(source: PanelSource, path: string, node: SchemaNode): ReactElement | null {
+	if (
+		node.hidden === true ||
+		holds(source, node.visibleWhen as Condition | undefined) === false
+	) {
+		return null;
+	}
+
+	const { translate } = source;
+	const title = node.title === undefined ? path : translate(node.title);
+	const subtitle = node.subtitle === undefined ? undefined : translate(node.subtitle);
+	const texts = [title, subtitle].filter((text) => text !== undefined);
+	const common = {
+		path,
+		title,
+		subtitle,
+		disabled: holds(source, node.disabledWhen as Condition | undefined) === true,
+	};
+
+	if (node.kind === 'notice') {
+		return createElement('NoticeRow', { key: path, ...common, tone: node.tone }, ...texts);
+	}
+
+	if (node.kind === 'button') {
+		return createElement(
+			'ButtonRow',
+			{
+				key: path,
+				...common,
+				variant: node.displayAs,
+				confirm: node.confirm === undefined ? undefined : translate(String(node.confirm)),
+				onPress: () => source.runAction(String(node.action)),
+			},
+			...texts,
+		);
+	}
+
+	return createElement(
+		rowName(node),
+		{
+			key: path,
+			...common,
+			value: source.read(path),
+			onChange: (value: SettingValue) => source.write(path, value),
+		},
+		...texts,
+	);
+}
+
+function section(source: PanelSource, path: string, node: SchemaNode): ReactElement | null {
+	if (
+		node.hidden === true ||
+		holds(source, node.visibleWhen as Condition | undefined) === false
+	) {
+		return null;
+	}
+
+	const title = node.title === undefined ? undefined : source.translate(node.title);
+	const rows = Object.entries(node.properties ?? {}).map(([key, child]) =>
+		row(source, path ? `${path}.${key}` : key, child),
+	);
+
+	return createElement(
+		'Section',
+		{ key: path || 'settings', path, title },
+		...(title === undefined ? [] : [title]),
+		...rows,
+	);
+}
+
+/**
+ * @description Creates the fake generated settings panel: one named row per setting, button and notice, grouped in a section
+ * per `setting.section`, with `hidden`, `visibleWhen` and `disabledWhen` honoured as the client's panel does.
+ * @param source The settings it draws, and what its rows call.
+ * @returns The panel component.
+ */
+export function createSettingsPanel(source: PanelSource): () => ReactElement {
+	function SettingsPanel() {
+		source.useChange();
+
+		const top: Record<string, SchemaNode> = {};
+		const sections: [string, SchemaNode][] = [];
+
+		for (const [key, node] of Object.entries(source.schema.properties)) {
+			if (node.kind === 'section') {
+				sections.push([key, node]);
+			} else {
+				top[key] = node;
+			}
+		}
+
+		return createElement(
+			'SettingsPanel',
+			{ schema: source.schema },
+			section(source, '', { kind: 'section', title: source.schema.title, properties: top }),
+			...sections.map(([key, node]) => section(source, key, node)),
+		);
+	}
+
+	return SettingsPanel;
+}

package/testing/fake-settings.ts

@@ -0,0 +1,428 @@
+import { createElement, useEffect, useState, type ReactElement } from 'react';
+
+import type { SettingsPayload } from '../src/storage';
+import type { MemoryStorage } from './memory-storage';
+import type { FakeModule } from './fake-metro';
+
+import { createSettingsPanel } from './fake-settings-panel';
+
+/**
+ * One node of a settings schema, as `@unbound-app/settings/schema`'s builders produce it once read as JSON. The
+ * options a builder copies that only the panel reads, such as `placeholder` or `action`, stay untyped.
+ */
+export type SchemaNode = FakeModule & {
+	kind: string;
+	displayAs?: string;
+	title?: string;
+	default?: SettingValue;
+	minimum?: number;
+	maximum?: number;
+	multipleOf?: number;
+	minLength?: number;
+	maxLength?: number;
+	alpha?: boolean;
+	minItems?: number;
+	maxItems?: number;
+	options?: SchemaChoice[];
+	of?: SchemaNode;
+	properties?: Record<string, SchemaNode>;
+};
+
+/** One option of a choice setting. */
+export type SchemaChoice = { const: string; title?: string };
+
+/** What `defineSettings` takes besides the settings. */
+export type DefineOptions = { title?: string };
+
+/** What `defineSettings` returns: the schema of a plugin's settings.ts. */
+export type SettingsSchema = SchemaNode & {
+	kind: 'settings';
+	properties: Record<string, SchemaNode>;
+};
+
+/** A value one setting holds. */
+export type SettingValue = string | number | boolean | string[];
+
+/** A plugin's settings as an object: reads apply defaults, writes are validated and saved. Sections nest. */
+export type SettingsValues = { [key: string]: SettingValue | SettingsValues };
+
+/** The fake `@unbound-app/settings`, bound to a memory Bucket. */
+export type FakeSettings = {
+	schema: SettingsSchema;
+	settings: SettingsValues;
+	/** Reads a setting, a section, or a section's setting by dot-separated key, and re-renders when it changes. */
+	useSetting: (key: string) => SettingValue | SettingsValues;
+	/** Puts every setting back to its default. */
+	resetSettings: () => void;
+	/** Saves a setting by dot-separated key; throws when the schema rejects the value. */
+	set: (key: string, value: SettingValue) => void;
+	SettingsPanel: () => ReactElement;
+	getSettingsPanel: () => ReactElement;
+};
+
+/** A builder's options: the plugin's generated typings check them; here they are read as plain JSON. */
+type Options = FakeModule;
+
+const COMMON = ['title', 'subtitle', 'hidden', 'requiresRestart'];
+const CONDITIONS = ['visibleWhen', 'disabledWhen'];
+const STRING = ['minLength', 'maxLength', 'placeholder', 'alpha', 'presets', 'palette', 'maxSize'];
+
+// Mirrors the build's builders: the JSON keeps these options, and a predicate becomes `{ predicate: true }`.
+function meta(kind: string, displayAs: string, options: Options, keys: string[] = []): SchemaNode {
+	const picked: SchemaNode = { kind, displayAs };
+
+	for (const key of [...COMMON, ...keys, 'default']) {
+		if (options[key] !== undefined) {
+			picked[key] = options[key];
+		}
+	}
+
+	for (const key of CONDITIONS) {
+		const condition = options[key];
+
+		if (condition !== undefined) {
+			// The panel runs the predicate the schema JSON drops: it rides on the marker, out of sight of equality and JSON.
+			picked[key] =
+				typeof condition === 'function'
+					? Object.defineProperty({ predicate: true }, 'run', { value: condition })
+					: condition;
+		}
+	}
+
+	return picked;
+}
+
+function numeric(kind: string, options: Options): SchemaNode {
+	const ranged = options.min !== undefined && options.max !== undefined;
+
+	return {
+		...meta(kind, options.displayAs ?? (ranged ? 'slider' : 'input'), options, ['units']),
+		...(typeof options.min === 'number' ? { minimum: options.min } : {}),
+		...(typeof options.max === 'number' ? { maximum: options.max } : {}),
+		...(typeof options.step === 'number' ? { multipleOf: options.step } : {}),
+	};
+}
+
+function choices(options: Options): SchemaChoice[] {
+	const labels: Options =
+		typeof options.options === 'object' && options.options ? options.options : {};
+	const entries = Object.entries(labels);
+
+	return entries.map(([value, label]) =>
+		typeof label === 'string' ? { const: value, title: label } : { const: value, ...label },
+	);
+}
+
+/** The `setting` builders of `@unbound-app/settings/schema`: one per stored primitive, `section`, `button` and `notice`; `displayAs` picks the widget. */
+export const setting = createSettingBuilders();
+
+function createSettingBuilders() {
+	return {
+		boolean: (options: Options = {}) => meta('boolean', options.displayAs ?? 'switch', options),
+		number: (options: Options = {}) => numeric('number', options),
+		integer: (options: Options = {}) => numeric('integer', options),
+		string: (options: Options = {}) =>
+			meta('string', options.displayAs ?? 'input', options, STRING),
+		choice(options: Options = {}): SchemaNode {
+			const list = choices(options);
+			const displayAs = options.displayAs ?? (list.length > 5 ? 'picker' : 'radio');
+
+			return { ...meta('choice', displayAs, options), options: list };
+		},
+		array(options: Options = {}): SchemaNode {
+			const of: Options =
+				typeof options.of === 'object' && options.of ? { ...options.of } : {};
+			const displayAs = options.displayAs ?? (of.kind === 'choice' ? 'checkboxes' : 'list');
+
+			delete of.default;
+
+			return {
+				...meta('array', displayAs, options, ['minItems', 'maxItems']),
+				of: { ...of, kind: String(of.kind) },
+			};
+		},
+		section: (options: Options, properties: Record<string, SchemaNode>): SchemaNode => ({
+			...meta('section', options.displayAs ?? 'group', options),
+			properties,
+		}),
+		button: (options: Options) =>
+			meta('button', options.displayAs ?? 'button', options, ['action', 'confirm']),
+		notice: (options: Options) => ({
+			...meta('notice', 'notice', options, ['tone']),
+			tone: options.tone ?? 'info',
+		}),
+	};
+}
+
+/**
+ * @description Declares a plugin's settings: the default export of its settings.ts.
+ * @param properties The settings, sections and actions, built with {@link setting}.
+ * @param options The message key of the title of the section holding the top-level settings.
+ * @returns The schema.
+ */
+export function defineSettings(
+	properties: Record<string, SchemaNode>,
+	options: DefineOptions = {},
+): SettingsSchema {
+	return {
+		kind: 'settings',
+		...(options.title === undefined ? {} : { title: options.title }),
+		properties,
+	};
+}
+
+function isMultiple(value: number, step: number): boolean {
+	const ratio = value / step;
+
+	return Math.abs(ratio - Math.round(ratio)) < 1e-9;
+}
+
+// Mirrors the client's `isSettingValue` for the checks a test can trip: the primitive, its range and its length.
+function isValue(field: SchemaNode, value: unknown): value is SettingValue {
+	switch (field.kind) {
+		case 'boolean':
+			return typeof value === 'boolean';
+		case 'string':
+			return (
+				typeof value === 'string' &&
+				value.length >= (field.minLength ?? 0) &&
+				value.length <= (field.maxLength ?? Infinity)
+			);
+		case 'choice':
+			return (field.options ?? []).some((choice) => choice.const === value);
+		case 'array':
+			return (
+				Array.isArray(value) &&
+				value.length >= (field.minItems ?? 0) &&
+				value.length <= (field.maxItems ?? Infinity) &&
+				new Set(value).size === value.length &&
+				value.every((item) => !field.of || isValue(field.of, item))
+			);
+		default:
+			return (
+				typeof value === 'number' &&
+				Number.isFinite(value) &&
+				(field.kind !== 'integer' || Number.isInteger(value)) &&
+				value >= (field.minimum ?? -Infinity) &&
+				value <= (field.maximum ?? Infinity) &&
+				(field.multipleOf === undefined || isMultiple(value, field.multipleOf))
+			);
+	}
+}
+
+// A setting whose builder took no default, such as an entity picker, reads empty.
+function emptyValue(field: SchemaNode): SettingValue {
+	switch (field.kind) {
+		case 'boolean':
+			return false;
+		case 'string':
+			return '';
+		case 'choice':
+			return field.options?.[0]?.const ?? '';
+		case 'array':
+			return [];
+		default:
+			return 0;
+	}
+}
+
+function entries(schema: SettingsSchema): [string, SchemaNode][] {
+	return Object.entries(schema.properties)
+		.flatMap(([key, node]): [string, SchemaNode][] =>
+			node.kind === 'section'
+				? Object.entries(node.properties ?? {}).map(([child, field]) => [
+						`${key}.${child}`,
+						field,
+					])
+				: [[key, node]],
+		)
+		.filter(([, field]) => field.kind !== 'button' && field.kind !== 'notice');
+}
+
+function affects(payload: SettingsPayload, key: string): boolean {
+	return (
+		payload.key === null ||
+		payload.key === key ||
+		key.startsWith(`${payload.key}.`) ||
+		payload.key.startsWith(`${key}.`)
+	);
+}
+
+/** What the generated panel reads besides the settings: message lookup and actions. */
+export type PanelOptions = {
+	/** Looks a message key up in the active locale, re-rendering when it changes. Defaults to the key. */
+	translate?: (key: string) => string;
+	/** Runs the export of the plugin's src/actions.ts a button names. Defaults to throwing, naming the action. */
+	runAction?: (name: string) => Promise<void>;
+};
+
+/**
+ * @description Binds a settings schema to a memory Bucket, as the client's `storage.define` does: defaults apply on
+ * read, and each write is checked against the schema.
+ * @param schema The schema settings.ts evaluated to.
+ * @param storage The memory storage holding the Bucket.
+ * @param bucketName The Bucket, the plugin's id.
+ * @param panel How the generated panel translates titles and runs buttons.
+ * @returns The settings, their hook, reset and panel.
+ */
+export function createFakeSettings(
+	schema: SettingsSchema,
+	storage: MemoryStorage,
+	bucketName: string,
+	panel: PanelOptions = {},
+): FakeSettings {
+	const bucket = storage.getBucket(bucketName);
+	const fields = new Map(entries(schema));
+
+	function field(key: string): SchemaNode {
+		const found = fields.get(key);
+
+		if (!found) {
+			throw new TypeError(`Failed to find setting ${key}: it is not in the schema.`);
+		}
+
+		return found;
+	}
+
+	function get(key: string): SettingValue {
+		const setting = field(key);
+		const stored = bucket.get<unknown>(key, undefined);
+
+		return isValue(setting, stored) ? stored : (setting.default ?? emptyValue(setting));
+	}
+
+	function set(key: string, value: SettingValue) {
+		if (!isValue(field(key), value)) {
+			throw new TypeError(
+				`Failed to set setting ${key}: ${JSON.stringify(value)} does not match its schema.`,
+			);
+		}
+
+		bucket.set(key, value);
+	}
+
+	function view(prefix: string, properties: Record<string, SchemaNode>): SettingsValues {
+		const sections = new Map<string, SettingsValues>();
+		const pathOf = (key: PropertyKey) => (prefix ? `${prefix}.${String(key)}` : String(key));
+		// A button or notice stores nothing, so it is not one of the settings.
+		const owns = (key: PropertyKey) =>
+			typeof key === 'string' &&
+			Object.hasOwn(properties, key) &&
+			properties[key]?.kind !== 'button' &&
+			properties[key]?.kind !== 'notice';
+
+		function read(key: string) {
+			const node = properties[key];
+
+			if (node?.kind !== 'section') {
+				return get(pathOf(key));
+			}
+
+			let section = sections.get(key);
+
+			if (!section) {
+				section = view(pathOf(key), node.properties ?? {});
+				sections.set(key, section);
+			}
+
+			return section;
+		}
+
+		return new Proxy<SettingsValues>(
+			{},
+			{
+				get: (_target, key) => (owns(key) ? read(String(key)) : undefined),
+				set(_target, key, value: SettingValue) {
+					const node = typeof key === 'string' ? properties[key] : undefined;
+
+					if (!node || node.kind === 'section') {
+						throw new TypeError(
+							`Failed to set setting ${pathOf(key)}: it is not a setting.`,
+						);
+					}
+
+					set(pathOf(key), value);
+
+					return true;
+				},
+				has: (_target, key) => owns(key),
+				ownKeys: () => Object.keys(properties).filter(owns),
+				getOwnPropertyDescriptor: (_target, key) =>
+					owns(key)
+						? {
+								value: read(String(key)),
+								writable: true,
+								enumerable: true,
+								configurable: true,
+							}
+						: undefined,
+			},
+		);
+	}
+
+	const values = view('', schema.properties);
+
+	function read(key: string): SettingValue | SettingsValues {
+		if (fields.has(key)) {
+			return get(key);
+		}
+
+		const section = values[key];
+
+		if (section === undefined) {
+			throw new TypeError(`Failed to find setting ${key}: it is not in the schema.`);
+		}
+
+		return section;
+	}
+
+	const SettingsPanel = createSettingsPanel({
+		schema,
+		values,
+		read,
+		write: set,
+		translate: panel.translate ?? ((key) => key),
+		runAction:
+			panel.runAction ??
+			(async (name) => {
+				throw new Error(`Failed to run action ${name}: the plugin has no src/actions.ts.`);
+			}),
+		useChange() {
+			const [, forceUpdate] = useState({});
+
+			useEffect(
+				() =>
+					storage.onChange(
+						(payload) => payload.store === bucketName,
+						() => forceUpdate({}),
+					),
+				[],
+			);
+		},
+	});
+
+	return {
+		schema,
+		settings: values,
+		set,
+		useSetting(key) {
+			const [, forceUpdate] = useState({});
+
+			useEffect(
+				() =>
+					storage.onChange(
+						(payload) => payload.store === bucketName && affects(payload, key),
+						() => forceUpdate({}),
+					),
+				[key],
+			);
+
+			return read(key);
+		},
+		resetSettings() {
+			for (const key of fields.keys()) bucket.remove(key);
+		},
+		SettingsPanel,
+		getSettingsPanel: () => createElement(SettingsPanel),
+	};
+}

package/testing/fake-timers.ts

@@ -0,0 +1,74 @@
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+type Schedule = <A extends unknown[]>(
+	callback: (...args: A) => void,
+	delay?: number,
+	...args: A
+) => TimerHandle;
+
+type Clear = (handle: TimerHandle | undefined) => void;
+
+/** The timer functions of the plugin scope: they run for real, and the scope clears what is still pending when the plugin stops. */
+export type FakeTimers = {
+	setTimeout: Schedule;
+	setInterval: Schedule;
+	clearTimeout: Clear;
+	clearInterval: Clear;
+	/** How many timeouts and intervals are scheduled and not yet run or cleared. */
+	pending: () => number;
+	/** Clears every pending timeout and interval, as the scope does on stop. */
+	clearAll: () => void;
+};
+
+/**
+ * @description Creates the scoped timers, over the timer functions that exist when it is called.
+ * @returns The timers.
+ */
+export function createFakeTimers(): FakeTimers {
+	const real = {
+		setTimeout: globalThis.setTimeout.bind(globalThis),
+		setInterval: globalThis.setInterval.bind(globalThis),
+		clearTimeout: globalThis.clearTimeout.bind(globalThis),
+		clearInterval: globalThis.clearInterval.bind(globalThis),
+	};
+	const pending = new Map<TimerHandle, Clear>();
+
+	function track(handle: TimerHandle, clear: Clear): TimerHandle {
+		pending.set(handle, clear);
+
+		return handle;
+	}
+
+	function release(handle: TimerHandle | undefined, clear: Clear) {
+		if (handle !== undefined) {
+			pending.delete(handle);
+		}
+
+		clear(handle);
+	}
+
+	return {
+		setTimeout(callback, delay, ...args) {
+			const handle = real.setTimeout(
+				(...params: typeof args) => {
+					pending.delete(handle);
+					callback(...params);
+				},
+				delay,
+				...args,
+			);
+
+			return track(handle, real.clearTimeout);
+		},
+		setInterval: (callback, delay, ...args) =>
+			track(real.setInterval(callback, delay, ...args), real.clearInterval),
+		clearTimeout: (handle) => release(handle, real.clearTimeout),
+		clearInterval: (handle) => release(handle, real.clearInterval),
+		pending: () => pending.size,
+		clearAll() {
+			for (const [handle, clear] of pending) clear(handle);
+
+			pending.clear();
+		},
+	};
+}