An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file touch-support-bundle.test.mjs
* @input Core's source, bundled with the PR size report's esbuild options
* (.github/scripts/lib/component-size.js); core's package.json; core's and
* the CLI's docs; core's and Lab's component source
* @output Pins architecture:react-component-runtime INV13's bundle and
* boundary claims: a public import of Core (each subpath, and each hook on
* its own) carries none of the gesture code unless it is listed as using a
* gesture, Button and TextInput never do, and a failure names the import
* chain that brings it; the root entry
* carries only the gesture code its touch components import; two components
* that import the touch module share one copy per page; only the internal
* `internal/touch` entry reaches it, and no consumer doc or component
* `import()` does; the names that entry gives Lab are not in the root
* entry
* @position Node test over source, so it needs no build. Its build files
* live under the repository's `node_modules/.cache`, never the system temp
* directory, whose listing esbuild would read for every build
*/
import fs from 'node:fs';
import {createRequire} from 'node:module';
import path from 'node:path';
import {afterAll, beforeAll, describe, expect, it} from 'vitest';
const REPO = path.resolve(import.meta.dirname, '..');
const CORE_SRC = path.join(REPO, 'packages/core/src');
const require = createRequire(path.join(REPO, 'package.json'));
const esbuild = require('esbuild');
/** The gesture core the internal entry re-exports. */
const PRIMITIVE_INPUT = /^packages\/core\/src\/gestures\//;
/**
* Where the builds' entry files live: under the repository's
* `node_modules/.cache`, not the system temp directory. esbuild reads the
* listing of every directory above each file it bundles, and on a shared
* machine the temp directory can hold hundreds of thousands of entries, so
* each build there read that listing first. The run's folder is made in
* beforeAll, not when the module loads: Vitest skips both hooks when a run
* filters out every test here.
*/
const CACHE = path.join(
REPO,
'node_modules/.cache/astryx-touch-support-bundle',
);
let scratch = '';
beforeAll(() => {
fs.mkdirSync(CACHE, {recursive: true});
scratch = fs.mkdtempSync(path.join(CACHE, 'run-'));
});
afterAll(() => {
fs.rmSync(scratch, {recursive: true, force: true});
});
/**
* The size report's build of a component import (minified ESM for the
* browser). React and StyleX stay external: they hold no touch code.
*/
const BUILD_OPTIONS = {
absWorkingDir: REPO,
// Never written (`write: false`): it only names the outputs.
outdir: path.join(CACHE, 'out'),
bundle: true,
minify: true,
format: 'esm',
platform: 'browser',
define: {'process.env.NODE_ENV': '"production"'},
loader: {'.css': 'empty'},
external: [
'react',
'react/*',
'react-dom',
'react-dom/*',
'@stylexjs/stylex',
],
metafile: true,
write: false,
logLevel: 'silent',
};
/**
* Each output of a build of `entries`, with the bytes each source module puts
* in it, built as the size report builds a component import.
*/
function outputsOf(entries) {
const result = esbuild.buildSync({
...BUILD_OPTIONS,
entryPoints: entries,
splitting: true,
});
return Object.values(result.metafile.outputs).map(output =>
Object.fromEntries(
Object.entries(output.inputs).map(([input, {bytesInOutput}]) => [
input,
bytesInOutput,
]),
),
);
}
/** The names a build of `entry` exports, read from esbuild's metafile. */
function exportsOf(entry) {
const result = esbuild.buildSync({...BUILD_OPTIONS, entryPoints: [entry]});
return Object.values(result.metafile.outputs).flatMap(
output => output.exports ?? [],
);
}
/**
* What the internal entry gives Lab components, none of it public API. Lab's
* refresh pull reads the pan, its hook, the motion engine, its motion math and
* companion curves, the scroll view's spring and the motion-role parsers.
* Other Lab components read the UIKit gesture table, the touch presentation
* and its query, and an element's direction. Lab's NavigationStack reads the
* screen-edge pan, the spring solver, the motion resolver, UIKit's
* navigation table and its four navigation springs. It also reads the focus
* helpers that follow the last input. Lab components that watch a finger's
* scroll read the finger-scroll watch. PageControl reads an element's shared
* animator, the Reduce Motion cross-fade, and the touch hit area's hook and
* layer.
*/
const LAB_ONLY_NAMES = [
'PanGestureRecognizer',
'useGestureRecognizer',
'useFingerScroll',
'createMotionEngine',
'cubicBezier',
'mapProgress',
'parseCssEasing',
'parseMotionRoleValue',
'rubberBand',
'rubberBandInverse',
'rubberBandSlope',
'scroll',
'isRtlElement',
'UIKIT_GESTURES',
'useTouchPresentation',
'TOUCH_QUERY',
'ScreenEdgePanGestureRecognizer',
'resolveMotion',
'solveSpring',
'toSpring',
'navigation',
'NAVIGATION_PUSH_SPRING',
'NAVIGATION_POP_SPRING',
'NAVIGATION_INTERACTIVE_POP_FINISH_SPRING',
'NAVIGATION_BAR_ELEMENTS_SPRING',
'focusForLastInput',
'isFocusLost',
'useInteractionModalityTracking',
'animatorFor',
'reducedMotionFade',
'useTouchHitArea',
'touchHitAreaStyles',
'measureLogicalScrollAxis',
];
/** The inputs matching `pattern` that put bytes in `bytes`. */
function bytesOf(bytes, pattern = PRIMITIVE_INPUT) {
return Object.entries(bytes).filter(
([input, size]) => pattern.test(input) && size > 0,
);
}
/** A scratch entry module with `source`. */
function entryWith(name, source) {
const file = path.join(scratch, name);
fs.writeFileSync(file, source);
return file;
}
/** Every file under `dir` whose name matches `pattern`. */
function filesUnder(dir, pattern) {
const found = [];
for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) {
if (entry.name !== 'node_modules' && entry.name !== 'dist') {
found.push(...filesUnder(full, pattern));
}
} else if (pattern.test(entry.name)) {
found.push(full);
}
}
return found;
}
/**
* The public imports that may carry the gesture code: those that use a
* gesture, or reach one through a component that does. Each is named here, so
* an import that starts carrying it shows up in review: the pull request that
* gives a component its gesture adds that component's import, and each import
* that reaches it, with a comment naming the gesture.
*/
const GESTURE_USERS = new Set([
// AlertDialog: its actions' press, tracked across both for a finger and a
// pen under the touch presentation.
'AlertDialog',
// ButtonGroup: a finger's or a pen's press, tracked across its buttons
// under the touch presentation.
'ButtonGroup',
// ToggleButton: through ToggleButtonGroup, whose toggles' press is tracked
// across them for a finger and a pen under the touch presentation.
'ToggleButton',
// Through AlertDialog: Tokenizer's bottom sheet confirms with an alert, and
// PowerSearch and Table's filtering render a Tokenizer. Both also reach
// TimeInput's wheels: PowerSearch's edit popover and Table's filtering.
'PowerSearch',
'Table',
'Tokenizer',
// Slider's thumb.
'Slider',
// Resizable: its drag tracks the release velocity that the lift's close and
// the handle's spring-back start from.
'Resizable',
// Switch: its press tracking and its drag, for every pointer.
'Switch',
// SegmentedControl: its press tracking and its drag, for every pointer.
'SegmentedControl',
// DateTimeInput: through the SegmentedControl its touch field renders.
'DateTimeInput',
// useScrollLock's page hold, and the imports that reach it. The sheet
// wheels of DateInput, TimeInput and DateTimeInput also drag and tap
// through the gesture system's pan and tap (DateInput/PickerWheel.tsx).
'hooks: useScrollLock',
'AppShell',
'BottomSheet',
'CommandPalette',
'ContextMenu',
'DateInput',
'Dialog',
'Drawer',
'DropdownMenu',
'Layer',
'Lightbox',
'Markdown',
'MobileNav',
'MoreMenu',
'MultiSelector',
'Pagination',
'Popover',
'Selector',
'SideNav',
'TimeInput',
'TopNav',
// Toast: its swipe's claim, a one-way pan whose first move decides.
'Toast',
// The public pan, which the root's createPanGesture shares.
'hooks: usePanGesture',
// The snap-point drag, which moves an element on that pan.
'hooks: useDragToSnapPoints',
// Snap paging: the pager, under a finger and on a trackpad swipe. Carousel
// imports none of it.
'SnapPaging',
]);
/** Public imports that carry no gesture code, whatever the list above says. */
const NEVER_GESTURE_USERS = ['Button', 'TextInput'];
/**
* Each public import of Core, built alone as the size report builds one:
* every subpath export but the root and the internal entries, and each export
* of the hooks entry on its own, since that barrel gathers independent hooks.
* The root re-exports all of them, so it is not one import: under INV13 a
* component that uses a gesture imports it statically, and the root then
* carries it by design.
*/
function publicImports() {
const pkg = JSON.parse(
fs.readFileSync(path.join(REPO, 'packages/core/package.json'), 'utf8'),
);
const imports = [];
for (const [subpath, target] of Object.entries(pkg.exports)) {
const source = target?.source;
if (
typeof source !== 'string' ||
!/\.tsx?$/.test(source) ||
subpath === '.' ||
subpath.includes('*') ||
subpath.startsWith('./internal/')
) {
continue;
}
const file = path.join(REPO, 'packages/core', source);
if (subpath === './hooks') {
for (const name of exportNamesOf(file)) {
imports.push({
name: `hooks: ${name}`,
source: `export {${name}} from ${JSON.stringify(file)};\n`,
});
}
} else {
imports.push({
name: subpath.slice(2),
source: `export * from ${JSON.stringify(file)};\n`,
});
}
}
return imports;
}
/** The names a module exports at runtime, read from its build. */
function exportNamesOf(file) {
const result = esbuild.buildSync({...BUILD_OPTIONS, entryPoints: [file]});
const entry = path.relative(REPO, file);
return Object.values(result.metafile.outputs).find(
output => output.entryPoint === entry,
).exports;
}
/**
* The gesture modules each of `imports` ships, with their bytes and the import
* chain that brings the first of them. Each import is an entry point of one
* build: without code splitting, each output holds only what its own entry
* reaches, so it is that import built on its own, and esbuild builds them all
* at once instead of one rebuild after another.
*/
async function gestureCarriers(imports) {
const dir = fs.mkdtempSync(path.join(scratch, 'public-imports-'));
const entries = imports.map(({source}, index) => {
const file = path.join(dir, `${index}.ts`);
fs.writeFileSync(file, source);
return path.relative(REPO, file);
});
const {metafile} = await esbuild.build({
...BUILD_OPTIONS,
entryPoints: entries.map(entry => path.join(REPO, entry)),
splitting: false,
});
const outputs = new Map(
Object.values(metafile.outputs).map(output => [output.entryPoint, output]),
);
const carriers = [];
imports.forEach(({name}, index) => {
const output = outputs.get(entries[index]);
if (output == null) {
throw new Error(`no output for the import of ${name}`);
}
const gestureModules = bytesOf(
Object.fromEntries(
Object.entries(output.inputs).map(([input, {bytesInOutput}]) => [
input,
bytesInOutput,
]),
),
);
if (gestureModules.length > 0) {
carriers.push({
name,
gestureModules,
chain: importChain(metafile, entries[index], gestureModules[0][0]),
});
}
});
return carriers;
}
/** The first import chain from `from` to `to` in a build's metafile. */
function importChain(metafile, from, to) {
const previous = new Map([[from, null]]);
const queue = [from];
while (queue.length > 0) {
const current = queue.shift();
if (current === to) {
break;
}
for (const {path: next} of metafile.inputs[current]?.imports ?? []) {
if (!previous.has(next) && metafile.inputs[next] != null) {
previous.set(next, current);
queue.push(next);
}
}
}
const chain = [];
for (let at = to; at != null; at = previous.get(at)) {
chain.unshift(at.replace('packages/core/src/', ''));
}
return chain.slice(1).join(' -> ');
}
describe('the touch module in bundles', () => {
it('is in no public import that uses no gesture', async () => {
const carriers = await gestureCarriers(publicImports());
const unexpected = carriers.filter(({name}) => !GESTURE_USERS.has(name));
expect(
unexpected.map(
({name, gestureModules, chain}) =>
`${name}: ${gestureModules
.map(
([input, size]) =>
`${input.replace('packages/core/src/', '')} ${size} B`,
)
.join(', ')} (via ${chain})`,
),
).toEqual([]);
}, 120_000);
it('is in none of the imports that never use a gesture', async () => {
const strict = publicImports().filter(({name}) =>
NEVER_GESTURE_USERS.includes(name),
);
expect(strict.map(({name}) => name).sort()).toEqual(
[...NEVER_GESTURE_USERS].sort(),
);
expect(
(await gestureCarriers(strict)).map(
({name, chain}) => `${name} (via ${chain})`,
),
).toEqual([]);
}, 120_000);
it('is in the root entry only as much as its touch components import', async () => {
const used = new Set(
(
await gestureCarriers(
publicImports().filter(({name}) => GESTURE_USERS.has(name)),
)
).flatMap(({gestureModules}) => gestureModules.map(([input]) => input)),
);
const inRoot = outputsOf([path.join(CORE_SRC, 'index.ts')]).flatMap(bytes =>
bytesOf(bytes).map(([input]) => input),
);
expect(
[...new Set(inRoot)]
.filter(input => !used.has(input))
.map(input => input.replace('packages/core/src/', '')),
).toEqual([]);
}, 120_000);
it('is absent from the utils entry', () => {
for (const bytes of outputsOf([path.join(CORE_SRC, 'utils/index.ts')])) {
expect(bytesOf(bytes)).toEqual([]);
}
});
it('is absent from a component that holds its layer (Layer/inputHold)', () => {
// A component in the root entry may hold its layer's input statically
// (a popover's presentation): the hold brings no gesture code with it.
const holder = entryWith(
'Holder.ts',
`import {holdInput} from ${JSON.stringify(
path.join(CORE_SRC, 'Layer/inputHold.ts'),
)};
export const Holder = holdInput;
`,
);
for (const bytes of outputsOf([holder])) {
expect(bytesOf(bytes)).toEqual([]);
}
});
it('is one copy that two components importing it share', () => {
const component = name =>
entryWith(
`${name}.ts`,
`import {GestureArena} from ${JSON.stringify(
path.join(CORE_SRC, 'internal/touch.ts'),
)};
export const ${name} = () => new GestureArena();
`,
);
const outputs = outputsOf([component('First'), component('Second')]);
const holding = outputs.filter(
bytes => bytes['packages/core/src/gestures/GestureArena.ts'] > 0,
);
expect(holding).toHaveLength(1);
for (const bytes of outputs.filter(output => output !== holding[0])) {
expect(bytesOf(bytes)).toEqual([]);
}
});
});
describe('the touch module internals', () => {
it('are built from files under the repository, not the system temp directory', () => {
expect(path.relative(REPO, scratch).split(path.sep)[0]).toBe(
'node_modules',
);
});
it('give Lab names that the public entry does not export', () => {
const internal = new Set(
exportsOf(path.join(CORE_SRC, 'internal/touch.ts')),
);
const root = new Set(exportsOf(path.join(CORE_SRC, 'index.ts')));
// The root build reads its exports: a public component is among them.
expect(root.has('Button')).toBe(true);
expect(LAB_ONLY_NAMES.filter(name => !internal.has(name))).toEqual([]);
expect(LAB_ONLY_NAMES.filter(name => root.has(name))).toEqual([]);
}, 120_000);
it('have no entry in the exports map beside the internal touch entry', () => {
const {exports} = JSON.parse(
fs.readFileSync(path.join(REPO, 'packages/core/package.json'), 'utf8'),
);
expect(exports['./internal/touch']?.source).toBe('./src/internal/touch.ts');
const other = Object.keys(exports).filter(key =>
/^\.\/(gestures|motion|touch-support)(\/|$)/.test(key),
);
expect(other).toEqual([]);
});
it('are named by no consumer doc', () => {
const docs = [
...filesUnder(CORE_SRC, /\.doc(\.[a-z]+)?\.mjs$/),
...filesUnder(path.join(REPO, 'packages/cli/assets/docs'), /\.mjs$/),
];
const naming = docs.filter(file =>
/\b(GestureArena|GestureRecognizer)\b|@astryxdesign\/core\/internal\//.test(
fs.readFileSync(file, 'utf8'),
),
);
expect(naming.map(file => path.relative(REPO, file))).toEqual([]);
});
it('are never loaded through an import() in Core or Lab source', () => {
const sources = [
...filesUnder(CORE_SRC, /\.(ts|tsx)$/),
...filesUnder(path.join(REPO, 'packages/lab/src'), /\.(ts|tsx)$/),
].filter(file => !/\.(test|spec)\.(ts|tsx)$|__tests__/.test(file));
const dynamic = sources.filter(file =>
/\bimport\(\s*['"][^'"]*(\/gestures\/|\/motion\/|touch-support|internal\/touch)/.test(
fs.readFileSync(file, 'utf8'),
),
);
expect(dynamic.map(file => path.relative(REPO, file))).toEqual([]);
});
});