@unbound-app/api 0.11.0 → 1.1.1

package/testing/fake-utils.ts

@@ -0,0 +1,216 @@
+import { useRef } from 'react';
+
+import type { TreeNode, TreePredicate, TreeSearchOptions } from '../src/utils/index';
+import type { PredicateResult } from '../src/_types';
+
+// These mirror the client's `utils` line for line: the testing kit ships without the client's private packages.
+
+/** What `findComponent` and `filterComponents` match by: a component name, or a predicate on each element. */
+type ComponentMatch = string | ((element: TreeNode) => PredicateResult);
+
+const ELEMENT_TYPES = new Set([
+	Symbol.for('react.transitional.element'),
+	Symbol.for('react.element'),
+]);
+const MEMO = Symbol.for('react.memo');
+const FORWARD_REF = Symbol.for('react.forward_ref');
+// The keys a React search descends into; `return` and `alternate` point back up, so it only goes down.
+const REACT_KEYS = [
+	'props',
+	'children',
+	'type',
+	'child',
+	'sibling',
+	'memoizedProps',
+	'memoizedState',
+	'stateNode',
+];
+// Elements nest through their props, so only `props` and `children` lead to more elements.
+const ELEMENT_OPTIONS: TreeSearchOptions = { walkable: ['props', 'children'] };
+
+function walkTree(
+	root: TreeNode,
+	predicate: TreePredicate,
+	options: TreeSearchOptions,
+	all: boolean,
+): TreeNode[] {
+	const { walkable, ignore = [], maxDepth = 100 } = options;
+	const seen = new WeakSet<object>();
+	const found: TreeNode[] = [];
+
+	// Returns `true` once the search should stop.
+	function visit(node: TreeNode, depth: number): boolean {
+		if (node === null || node === undefined) {
+			return false;
+		}
+
+		const isObject = typeof node === 'object';
+
+		if (isObject) {
+			if (seen.has(node)) {
+				return false;
+			}
+
+			seen.add(node);
+		}
+
+		if (predicate(node)) {
+			found.push(node);
+
+			if (!all) {
+				return true;
+			}
+		}
+
+		if (!isObject || depth >= maxDepth) {
+			return false;
+		}
+
+		const keys = Array.isArray(node) ? node.keys() : (walkable ?? Object.keys(node));
+
+		for (const key of keys) {
+			if (typeof key === 'string' && ignore.includes(key)) {
+				continue;
+			}
+
+			if (visit(node[key], depth + 1)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	visit(root, 0);
+
+	return found;
+}
+
+function reactOptions({ walkable = [], ...rest }: TreeSearchOptions): TreeSearchOptions {
+	return { ...rest, walkable: [...REACT_KEYS, ...walkable] };
+}
+
+function isElement(node: TreeNode): boolean {
+	return typeof node === 'object' && ELEMENT_TYPES.has(node.$$typeof);
+}
+
+function isNamed(type: TreeNode, name: string): boolean {
+	if (typeof type === 'string') {
+		return type === name;
+	}
+
+	if (!type) {
+		return false;
+	}
+
+	if (type.displayName === name) {
+		return true;
+	}
+
+	if (type.$$typeof === MEMO) {
+		return isNamed(type.type, name);
+	}
+
+	if (type.$$typeof === FORWARD_REF) {
+		return isNamed(type.render, name);
+	}
+
+	return typeof type === 'function' && type.name === name;
+}
+
+function elementPredicate(match: ComponentMatch): TreePredicate {
+	return (node) =>
+		isElement(node) && (typeof match === 'string' ? isNamed(node.type, match) : match(node));
+}
+
+function sameEntries(left: Iterable<[unknown, unknown]>, right: Map<unknown, unknown>): boolean {
+	return [...left].every(([key, value]) => right.has(key) && Object.is(value, right.get(key)));
+}
+
+function shallow<T>(previous: T, next: T): boolean {
+	if (Object.is(previous, next)) {
+		return true;
+	}
+
+	if (
+		typeof previous !== 'object' ||
+		previous === null ||
+		typeof next !== 'object' ||
+		next === null
+	) {
+		return false;
+	}
+
+	if (previous instanceof Map && next instanceof Map) {
+		return previous.size === next.size && sameEntries(previous, next);
+	}
+
+	if (previous instanceof Set && next instanceof Set) {
+		return previous.size === next.size && [...previous].every((item) => next.has(item));
+	}
+
+	const left = Object.entries(previous);
+
+	return (
+		left.length === Object.keys(next).length && sameEntries(left, new Map(Object.entries(next)))
+	);
+}
+
+function useShallow<S, U>(selector: (state: S) => U): (state: S) => U {
+	const previous = useRef<U | undefined>(undefined);
+
+	return (state) => {
+		const next = selector(state);
+
+		if (previous.current !== undefined && shallow(previous.current, next)) {
+			return previous.current;
+		}
+
+		previous.current = next;
+
+		return next;
+	};
+}
+
+function findInTree<T = TreeNode>(
+	root: TreeNode,
+	predicate: TreePredicate,
+	options: TreeSearchOptions = {},
+): T | undefined {
+	return walkTree(root, predicate, options, false)[0];
+}
+
+function filterInTree<T = TreeNode>(
+	root: TreeNode,
+	predicate: TreePredicate,
+	options: TreeSearchOptions = {},
+): T[] {
+	return walkTree(root, predicate, options, true);
+}
+
+/**
+ * @description Creates the fake `utils`: the client's tree searches, component finders and shallow comparison, over any object graph.
+ * @returns The namespace, with `react` nested as on device.
+ */
+export function createFakeUtils() {
+	const react = {
+		findComponent: (tree: TreeNode, match: ComponentMatch) =>
+			findInTree(tree, elementPredicate(match), ELEMENT_OPTIONS),
+		filterComponents: (tree: TreeNode, match: ComponentMatch) =>
+			filterInTree(tree, elementPredicate(match), ELEMENT_OPTIONS),
+		findInTree: <T = TreeNode>(
+			root: TreeNode,
+			predicate: TreePredicate,
+			options?: TreeSearchOptions,
+		) => findInTree<T>(root, predicate, reactOptions(options ?? {})),
+		filterInTree: <T = TreeNode>(
+			root: TreeNode,
+			predicate: TreePredicate,
+			options?: TreeSearchOptions,
+		) => filterInTree<T>(root, predicate, reactOptions(options ?? {})),
+		shallow,
+		useShallow,
+	};
+
+	return { findInTree, filterInTree, react };
+}

package/testing/icu-format.ts

@@ -0,0 +1,132 @@
+import {
+	parseIcu,
+	type IcuArgumentNode,
+	type IcuNode,
+	type IcuPluralNode,
+	type IcuSelectNode,
+} from './icu-parse';
+
+/** A value `format` puts into a placeholder, as the client's `FormatVars` types it. */
+export type IcuValue = string | number | boolean | Date;
+
+/** The values of a message's placeholders, by name. */
+export type IcuVars = Record<string, IcuValue>;
+
+const DATE_STYLES = new Set(['short', 'medium', 'long', 'full']);
+
+function numberOptions(style: string): Intl.NumberFormatOptions {
+	if (style === 'integer') {
+		return { maximumFractionDigits: 0 };
+	}
+
+	if (style === 'percent') {
+		return { style: 'percent' };
+	}
+
+	return {};
+}
+
+function dateOptions(type: string, style: string): Intl.DateTimeFormatOptions {
+	const picked = DATE_STYLES.has(style) ? style : 'medium';
+	const value = picked as NonNullable<Intl.DateTimeFormatOptions['dateStyle']>;
+
+	return type === 'time' ? { timeStyle: value } : { dateStyle: value };
+}
+
+function valueOf(vars: IcuVars, name: string): IcuValue {
+	const value = vars[name];
+
+	if (value === undefined) {
+		throw new Error(`Failed to format a message: no value for {${name}}.`);
+	}
+
+	return value;
+}
+
+function formatArgument(node: IcuArgumentNode, vars: IcuVars, locale: string) {
+	const value = valueOf(vars, node.name);
+
+	if (node.type === 'number') {
+		return new Intl.NumberFormat(locale, numberOptions(node.style)).format(Number(value));
+	}
+
+	if (node.type === 'date' || node.type === 'time') {
+		const date = value instanceof Date ? value : new Date(Number(value));
+
+		return new Intl.DateTimeFormat(locale, dateOptions(node.type, node.style)).format(date);
+	}
+
+	return value instanceof Date ? value.toISOString() : String(value);
+}
+
+// A plural or select without `other` has nothing to fall back to, so formatting it throws.
+function otherBranch(node: IcuPluralNode | IcuSelectNode): IcuNode[] {
+	const other = node.branches.get('other');
+
+	if (!other) {
+		throw new Error(`Failed to format a message: {${node.name}} has no "other" branch.`);
+	}
+
+	return other;
+}
+
+function pickPlural(node: IcuPluralNode, value: number, locale: string) {
+	const exact = node.branches.get(`=${value}`);
+
+	if (exact) {
+		return exact;
+	}
+
+	const rules = new Intl.PluralRules(locale, { type: node.ordinal ? 'ordinal' : 'cardinal' });
+
+	return node.branches.get(rules.select(value - node.offset)) ?? otherBranch(node);
+}
+
+function formatNodes(nodes: IcuNode[], vars: IcuVars, locale: string, pound?: number): string {
+	let output = '';
+
+	for (const node of nodes) {
+		switch (node.kind) {
+			case 'text':
+				output += node.text;
+				break;
+			case 'pound':
+				output += pound === undefined ? '#' : new Intl.NumberFormat(locale).format(pound);
+				break;
+			case 'argument':
+				output += formatArgument(node, vars, locale);
+				break;
+			case 'plural': {
+				const value = Number(valueOf(vars, node.name));
+
+				output += formatNodes(
+					pickPlural(node, value, locale),
+					vars,
+					locale,
+					value - node.offset,
+				);
+				break;
+			}
+			case 'select': {
+				const value = String(valueOf(vars, node.name));
+				const branch = node.branches.get(value) ?? otherBranch(node);
+
+				output += formatNodes(branch, vars, locale, pound);
+				break;
+			}
+		}
+	}
+
+	return output;
+}
+
+/**
+ * @description Formats an ICU MessageFormat string in a locale, as Discord's `MessageFormat` does on device.
+ * @param message The message.
+ * @param vars The values of its placeholders; a placeholder without one throws.
+ * @param locale The locale plural rules, numbers and dates follow, such as `de`.
+ * @returns The formatted message.
+ */
+export function formatIcu(message: string, vars: IcuVars = {}, locale: string = 'en-US'): string {
+	return formatNodes(parseIcu(message), vars, locale);
+}

package/testing/icu-parse.ts

@@ -0,0 +1,277 @@
+/** The branches of a `plural`, `selectordinal` or `select` argument, by selector, such as `one` or `=0`. */
+export type IcuBranches = Map<string, IcuNode[]>;
+
+/** A simple argument: `{name}`, or a formatted one such as `{count, number, integer}`. */
+export type IcuArgumentNode = { kind: 'argument'; name: string; type: string; style: string };
+
+/** A `plural` or `selectordinal` argument. */
+export type IcuPluralNode = {
+	kind: 'plural';
+	name: string;
+	ordinal: boolean;
+	offset: number;
+	branches: IcuBranches;
+};
+
+/** A `select` argument. */
+export type IcuSelectNode = { kind: 'select'; name: string; branches: IcuBranches };
+
+/** One piece of a parsed ICU MessageFormat string. */
+export type IcuNode =
+	| { kind: 'text'; text: string }
+	| { kind: 'pound' }
+	| IcuArgumentNode
+	| IcuPluralNode
+	| IcuSelectNode;
+
+/** A syntax error in an ICU message; `position` is the 1-based character it stopped at. */
+export class IcuSyntaxError extends Error {
+	readonly position: number;
+
+	// Node's strip-only TypeScript, which loads this under the CLI's `rollup -c`, has no parameter properties.
+	constructor(reason: string, position: number) {
+		super(`${reason} at character ${position}`);
+		this.position = position;
+	}
+}
+
+type Reader = { text: string; index: number };
+
+type BranchList = { branches: IcuBranches; offset: number };
+
+function isSpace(char: string): boolean {
+	return char !== '' && char.trim() === '';
+}
+
+function fail(reader: Reader, reason: string): never {
+	throw new IcuSyntaxError(reason, reader.index + 1);
+}
+
+function peek(reader: Reader): string {
+	return reader.text[reader.index] ?? '';
+}
+
+function skipSpace(reader: Reader) {
+	while (isSpace(peek(reader))) reader.index++;
+}
+
+function readWord(reader: Reader): string {
+	skipSpace(reader);
+
+	const start = reader.index;
+
+	while (reader.index < reader.text.length) {
+		const char = peek(reader);
+
+		if (isSpace(char) || char === ',' || char === '{' || char === '}') {
+			break;
+		}
+
+		reader.index++;
+	}
+
+	return reader.text.slice(start, reader.index);
+}
+
+function expect(reader: Reader, char: string) {
+	skipSpace(reader);
+
+	if (peek(reader) !== char) {
+		fail(reader, `Expected "${char}"`);
+	}
+
+	reader.index++;
+}
+
+// An apostrophe quotes a following `{`, `}` or (in a plural) `#` up to the next lone apostrophe; `''` is one apostrophe.
+function readQuoted(reader: Reader, inPlural: boolean): string {
+	const next = reader.text[reader.index + 1] ?? '';
+
+	if (next === "'") {
+		reader.index += 2;
+
+		return "'";
+	}
+
+	if (next !== '{' && next !== '}' && !(inPlural && next === '#')) {
+		reader.index++;
+
+		return "'";
+	}
+
+	let quoted = '';
+
+	reader.index++;
+
+	while (reader.index < reader.text.length) {
+		const char = peek(reader);
+
+		if (char === "'" && reader.text[reader.index + 1] === "'") {
+			quoted += "'";
+			reader.index += 2;
+		} else if (char === "'") {
+			reader.index++;
+
+			return quoted;
+		} else {
+			quoted += char;
+			reader.index++;
+		}
+	}
+
+	return quoted;
+}
+
+function readMessage(reader: Reader, nested: boolean, inPlural: boolean): IcuNode[] {
+	const nodes: IcuNode[] = [];
+	let text = '';
+
+	function flush() {
+		if (text) {
+			nodes.push({ kind: 'text', text });
+		}
+
+		text = '';
+	}
+
+	while (reader.index < reader.text.length) {
+		const char = peek(reader);
+
+		if (char === "'") {
+			text += readQuoted(reader, inPlural);
+		} else if (char === '{') {
+			flush();
+			reader.index++;
+			nodes.push(readArgument(reader));
+		} else if (char === '}') {
+			if (!nested) {
+				fail(reader, 'Unmatched "}"');
+			}
+
+			flush();
+
+			return nodes;
+		} else if (char === '#' && inPlural) {
+			flush();
+			nodes.push({ kind: 'pound' });
+			reader.index++;
+		} else {
+			text += char;
+			reader.index++;
+		}
+	}
+
+	if (nested) {
+		fail(reader, 'Unclosed "{"');
+	}
+
+	flush();
+
+	return nodes;
+}
+
+function readBranches(reader: Reader, inPlural: boolean): BranchList {
+	const branches: IcuBranches = new Map();
+	let offset = 0;
+
+	skipSpace(reader);
+
+	while (reader.index < reader.text.length && peek(reader) !== '}') {
+		const selector = readWord(reader);
+
+		if (!selector) {
+			fail(reader, 'Expected a selector');
+		}
+
+		if (selector.startsWith('offset:')) {
+			offset = Number(selector.slice('offset:'.length));
+		} else {
+			expect(reader, '{');
+			branches.set(selector, readMessage(reader, true, inPlural));
+			expect(reader, '}');
+		}
+
+		skipSpace(reader);
+	}
+
+	return { branches, offset };
+}
+
+function readStyle(reader: Reader): string {
+	const start = reader.index;
+	let depth = 0;
+
+	while (reader.index < reader.text.length) {
+		const char = peek(reader);
+
+		if (char === '}' && depth === 0) {
+			return reader.text.slice(start, reader.index).trim();
+		}
+
+		if (char === '{') {
+			depth++;
+		}
+
+		if (char === '}') {
+			depth--;
+		}
+
+		reader.index++;
+	}
+
+	return fail(reader, 'Unclosed argument');
+}
+
+function readArgument(reader: Reader): IcuNode {
+	const name = readWord(reader);
+
+	if (!name) {
+		fail(reader, 'Expected an argument name');
+	}
+
+	skipSpace(reader);
+
+	if (peek(reader) === '}') {
+		reader.index++;
+
+		return { kind: 'argument', name, type: '', style: '' };
+	}
+
+	expect(reader, ',');
+
+	const type = readWord(reader);
+	let node: IcuNode;
+
+	skipSpace(reader);
+
+	if (type === 'plural' || type === 'selectordinal') {
+		expect(reader, ',');
+
+		const { branches, offset } = readBranches(reader, true);
+
+		node = { kind: 'plural', name, ordinal: type === 'selectordinal', offset, branches };
+	} else if (type === 'select') {
+		expect(reader, ',');
+		node = { kind: 'select', name, branches: readBranches(reader, false).branches };
+	} else {
+		if (peek(reader) === ',') {
+			reader.index++;
+		}
+
+		node = { kind: 'argument', name, type, style: readStyle(reader) };
+	}
+
+	expect(reader, '}');
+
+	return node;
+}
+
+/**
+ * @description Parses an ICU MessageFormat string: arguments, `number`/`date`/`time`, `plural`, `selectordinal`,
+ * `select`, `#`, `offset:` and apostrophe quoting. The CLI's i18n typings and checks and the testing kit share it.
+ * @param message The message, such as `{count, plural, one {# file} other {# files}}`.
+ * @returns The message's nodes; throws an `IcuSyntaxError` naming the position of a syntax error.
+ */
+export function parseIcu(message: string): IcuNode[] {
+	return readMessage({ text: message, index: 0 }, false, false);
+}

package/testing/index.ts

@@ -0,0 +1,42 @@
+export {
+	toasts,
+	dialogs,
+	commands,
+	patches,
+	flux,
+	metro,
+	native,
+	plugins,
+	fs,
+	logs,
+	setLocale,
+	extendApi,
+} from './recorders';
+export { act, createTestRenderer, type TestRenderer } from './test-renderer';
+export { startPlugin, stopPlugin, pluginHolds } from './plugin-lifecycle';
+export { render, type RenderOptions, type RenderResult } from './render';
+export * from './install-addon-globals';
+export * from './fake-native-bridge';
+export * from './fake-react-native';
+export * from './listener-registry';
+export * from './recording-patcher';
+export * from './fake-components';
+export * from './memory-storage';
+export * from './fake-feedback';
+export * from './fake-settings';
+export * from './fake-locales';
+export * from './fake-plugins';
+export * from './plugin-types';
+export * from './fake-native';
+export * from './fake-timers';
+export * from './react-value';
+export * from './fake-metro';
+export * from './fake-react';
+export * from './fake-utils';
+export * from './icu-format';
+export * from './fake-java';
+export * from './fake-objc';
+export * from './icu-parse';
+export * from './test-node';
+export * from './fake-api';
+export * from './fake-fs';