@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/motion/roleValue.ts

@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file roleValue.ts
+ * @input A role id, or a role's kind and value
+ * @output isMotionRoleId, motionRoleVariable and formatMotionRoleValue (a
+ *   role value's CSS form), with the role kinds
+ * @position The value half of the internal motion roles: no registry and
+ *   no parsing. roles.ts holds the registry and re-exports these.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/roles.test.ts.
+ */
+
+import {durationBounceOf, toSpring, type SpringDescription} from './spring';
+
+/** The three kinds of value a role can hold. */
+export type MotionRoleKind = 'spring' | 'duration' | 'curve';
+
+/** Cubic-bézier control points `[x1, y1, x2, y2]`. */
+export type MotionCurvePoints = readonly [number, number, number, number];
+
+const ROLE_ID = /^[a-z][A-Za-z0-9]*(\.[a-z][A-Za-z0-9]*)+$/;
+
+/** Whether `id` is a well-formed role name (a dotted table path). */
+export function isMotionRoleId(id: string): boolean {
+  return ROLE_ID.test(id);
+}
+
+/** The CSS custom property for a role: `--motion-` + the path in kebab case. */
+export function motionRoleVariable(id: string): string {
+  if (!isMotionRoleId(id)) {
+    throw new Error(
+      `motion role "${id}" must be a dotted table path such as "springs.sheetPresent"`,
+    );
+  }
+  return `--motion-${id
+    .split('.')
+    .map(part => part.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`))
+    .join('-')}`;
+}
+
+export function isSpring(value: unknown): value is SpringDescription {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  return (
+    ('response' in value && 'dampingRatio' in value) ||
+    ('duration' in value && 'bounce' in value) ||
+    ('stiffness' in value && 'damping' in value)
+  );
+}
+
+export function isCurve(value: unknown): value is MotionCurvePoints {
+  return (
+    Array.isArray(value) &&
+    value.length === 4 &&
+    value.every(n => typeof n === 'number')
+  );
+}
+
+/** Six significant digits: enough for any motion, free of float noise. */
+export function short(n: number): string {
+  return String(Number(n.toPrecision(6)));
+}
+
+/**
+ * A role value as its CSS custom property holds it:
+ * - spring: SwiftUI's duration and bounce, `0.5s 0.15` (exact for every
+ *   spring: mass folds into the duration, overdamping into a negative bounce);
+ * - duration: `250ms`;
+ * - curve: `cubic-bezier(0.42, 0, 0.58, 1)`, usable as is in CSS.
+ * Throws on a value that is not a valid value of its kind.
+ */
+export function formatMotionRoleValue(
+  kind: MotionRoleKind,
+  value: unknown,
+): string {
+  if (kind === 'spring') {
+    if (!isSpring(value)) {
+      throw new TypeError(
+        'a spring is {response, dampingRatio}, {duration, bounce} or {mass?, stiffness, damping}',
+      );
+    }
+    const {duration, bounce} = durationBounceOf(toSpring(value));
+    if (!(bounce < 1)) {
+      throw new RangeError(
+        'a spring must settle: its bounce must be below 1 (a damping ratio above 0)',
+      );
+    }
+    return `${short(duration)}s ${short(bounce)}`;
+  }
+  if (kind === 'duration') {
+    if (!(typeof value === 'number' && Number.isFinite(value) && value >= 0)) {
+      throw new TypeError('a duration is a finite number of milliseconds ≥ 0');
+    }
+    return `${short(value)}ms`;
+  }
+  if (!isCurve(value) || !value.every(Number.isFinite)) {
+    throw new TypeError('a curve is four finite numbers [x1, y1, x2, y2]');
+  }
+  if (value[0] < 0 || value[0] > 1 || value[2] < 0 || value[2] > 1) {
+    throw new RangeError("a curve's x1 and x2 must lie in [0, 1]");
+  }
+  return `cubic-bezier(${value.map(short).join(', ')})`;
+}

package/src/motion/roles.test.ts

@@ -0,0 +1,256 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file roles.test.ts
+ * @input roles.ts and the shared UIKit tables (registered on import)
+ * @output Proof that each spring, duration and curve of a registered table is
+ *   a role named by its path, that non-motion values are not, and that a
+ *   role's CSS value reads back as the same motion
+ * @position Testing for /packages/core/src/motion/roles.ts
+ */
+
+import {readFileSync} from 'node:fs';
+import {resolve} from 'node:path';
+import {describe, expect, it} from 'vitest';
+import {
+  formatMotionRoleValue,
+  isMotionRoleId,
+  listMotionRoles,
+  motionRoleIn,
+  motionRoleOf,
+  motionRoleVariable,
+  parseMotionRoleValue,
+  registerMotionTable,
+} from './roles';
+import {dampingRatioOf, naturalFrequency, toSpring} from './spring';
+import {navigation, scroll, springs, timing} from './uikit';
+import {
+  motionTableFiles,
+  REGISTER_EXPORT,
+} from '../../../../scripts/motion-table-files.mjs';
+
+// Every table the role list is generated from, registered the way the
+// generator does: through each module's register<Name>Table.
+for (const file of motionTableFiles(resolve(__dirname, '..'))) {
+  const module = (await import(file)) as Record<string, unknown>;
+  for (const [name, value] of Object.entries(module)) {
+    if (REGISTER_EXPORT.test(name) && typeof value === 'function') {
+      (value as () => void)();
+    }
+  }
+}
+// The tables that discovery registered, before any test adds a fixture.
+const DISCOVERED = new Set(
+  listMotionRoles().map(role => role.id.split('.')[0]),
+);
+
+describe('motion roles', () => {
+  it('names a role by its table path, and its CSS variable in kebab case', () => {
+    expect(isMotionRoleId('sheet.present')).toBe(true);
+    expect(isMotionRoleId('timing.curves.move')).toBe(true);
+    expect(isMotionRoleId('sheet')).toBe(false);
+    expect(isMotionRoleId('Sheet.present')).toBe(false);
+    expect(motionRoleVariable('springs.sheetDetent')).toBe(
+      '--motion-springs-sheet-detent',
+    );
+    expect(motionRoleVariable('timing.curves.move')).toBe(
+      '--motion-timing-curves-move',
+    );
+    expect(() => motionRoleVariable('sheet')).toThrow(/dotted table path/);
+  });
+
+  it('leaves a table value FR4 does not name an internal constant', () => {
+    const shared = {response: 0.4, dampingRatio: 0.9};
+    const table = {
+      present: shared,
+      dismiss: shared,
+      fadeMs: 200,
+      curves: {out: [0, 0, 0.58, 1] as const},
+    };
+    registerMotionTable('fixture', table);
+    // No role, no CSS variable, and the table is untouched.
+    expect(motionRoleOf(table.present)).toBeUndefined();
+    expect(table.dismiss).toBe(table.present);
+    expect(motionRoleIn(table, 'fadeMs')).toBeUndefined();
+    expect(motionRoleOf(table.curves.out)).toBeUndefined();
+    expect(listMotionRoles().some(role => role.id.startsWith('fixture.'))).toBe(
+      false,
+    );
+  });
+
+  it('has exactly the roles spec:AST-094 FR4 names', () => {
+    const spec = readFileSync(
+      resolve(
+        __dirname,
+        '../../../../docs/specs/AST-094-touch-presentations/spec.md',
+      ),
+      'utf8',
+    );
+    const fr4 = spec.slice(spec.indexOf('**FR4'), spec.indexOf('**FR5'));
+    const named = [...fr4.matchAll(/^\s*\| `([a-z][\w.]*)`\s*\|/gm)].map(
+      match => match[1],
+    );
+    expect(named.length).toBeGreaterThan(0);
+    // Every table registered, the roles are exactly FR4's (other tests
+    // here register a fixture, which lists none).
+    expect(new Set(listMotionRoles().map(role => role.id))).toEqual(
+      new Set(named),
+    );
+  });
+
+  it('names the shared roles for their use, as spec:AST-094 FR4 does', () => {
+    expect(
+      [
+        springs.fingerTracking,
+        springs.emphasis,
+        springs.settle,
+        springs.quickChange,
+        springs.viewChange,
+        springs.timedChange,
+        springs.stateChange,
+        springs.directChange,
+        springs.menuOpen,
+        springs.menuClose,
+        timing.curves.viewChange,
+        timing.curves.exit,
+        timing.curves.entrance,
+        timing.curves.move,
+      ].map(leaf => motionRoleOf(leaf)?.id),
+    ).toEqual([
+      'springs.fingerTracking',
+      'springs.emphasis',
+      'springs.settle',
+      'springs.quickChange',
+      'springs.viewChange',
+      'springs.timedChange',
+      'springs.stateChange',
+      'springs.directChange',
+      'springs.menuOpen',
+      'springs.menuClose',
+      'timing.curves.viewChange',
+      'timing.curves.exit',
+      'timing.curves.entrance',
+      'timing.curves.move',
+    ]);
+    expect(motionRoleIn(timing, 'stateChangeMs')?.id).toBe(
+      'timing.stateChangeMs',
+    );
+    // A preset or curve-shape name is no role id.
+    for (const old of [
+      'springs.smooth',
+      'springs.bouncy',
+      'timing.curves.easeInOut',
+      'timing.implicitAnimationMs',
+    ]) {
+      expect(listMotionRoles().map(role => role.id)).not.toContain(old);
+    }
+  });
+
+  it("leaves the keyboard's motion out: it rides the keyboard (FR4)", () => {
+    expect(motionRoleOf(springs.keyboard)).toBeUndefined();
+    expect(motionRoleIn(timing, 'keyboardNotificationMs')).toBeUndefined();
+  });
+
+  it('refuses a spring that never settles', () => {
+    expect(() =>
+      formatMotionRoleValue('spring', {duration: 0.5, bounce: 1}),
+    ).toThrow(/must settle/);
+    expect(() =>
+      formatMotionRoleValue('spring', {response: 0.5, dampingRatio: 0}),
+    ).toThrow(/must settle/);
+    expect(parseMotionRoleValue('spring', '0.5s 1')).toBeNull();
+  });
+
+  it('makes the roles of the shared tables, and keeps every other value internal', () => {
+    expect(motionRoleOf(springs.viewChange)?.id).toBe('springs.viewChange');
+    expect(motionRoleOf(timing.curves.move)?.kind).toBe('curve');
+    expect(motionRoleIn(timing, 'stateChangeMs')?.kind).toBe('duration');
+    // A component's measured value is an internal constant, not a role.
+    expect(motionRoleOf(springs.sheetPresent)).toBeUndefined();
+    expect(springs.sheetPresent).toEqual(springs.viewChange);
+    expect(motionRoleOf(scroll.bounce)).toBeUndefined();
+    expect(motionRoleIn(timing.press, 'flashMs')).toBeUndefined();
+    expect(motionRoleIn(navigation, 'transitionMs')).toBeUndefined();
+    // The Reduced Motion fade, UIKit's menu spring under Reduce Motion, the
+    // thresholds and the arbitration timings are not motion roles either.
+    expect(motionRoleIn(timing, 'reducedMotionCrossFadeMs')).toBeUndefined();
+    expect(motionRoleOf(springs.menuReducedMotion)).toBeUndefined();
+    expect(motionRoleIn(timing.press, 'scrollBrakeMs')).toBeUndefined();
+    expect(motionRoleIn(scroll, 'delaysContentTouchesMs')).toBeUndefined();
+    expect(motionRoleIn(navigation, 'parallax')).toBeUndefined();
+    const ids = listMotionRoles().map(role => role.id);
+    expect(ids.some(id => id.startsWith('gestures.'))).toBe(false);
+    // Every role has its own CSS variable.
+    const variables = listMotionRoles().map(role => role.variable);
+    expect(new Set(variables).size).toBe(variables.length);
+  });
+
+  it('registers exactly the roles spec:AST-094 FR4 names, internally', () => {
+    // Every table discovery registered (other tests here add fixtures).
+    const discovered = listMotionRoles().filter(role =>
+      DISCOVERED.has(role.id.split('.')[0]),
+    );
+    expect(
+      Object.fromEntries(discovered.map(role => [role.id, role.kind])),
+    ).toEqual({
+      'springs.directChange': 'spring',
+      'springs.emphasis': 'spring',
+      'springs.fingerTracking': 'spring',
+      'springs.menuClose': 'spring',
+      'springs.menuOpen': 'spring',
+      'springs.quickChange': 'spring',
+      'springs.settle': 'spring',
+      'springs.stateChange': 'spring',
+      'springs.subMenuBack': 'spring',
+      'springs.subMenuOpen': 'spring',
+      'springs.timedChange': 'spring',
+      'springs.viewChange': 'spring',
+      'timing.curves.entrance': 'curve',
+      'timing.curves.exit': 'curve',
+      'timing.curves.move': 'curve',
+      'timing.curves.viewChange': 'curve',
+      'timing.stateChangeMs': 'duration',
+    });
+  });
+
+  it('writes every table value in CSS form and reads back the same motion', () => {
+    for (const role of listMotionRoles()) {
+      const text = formatMotionRoleValue(role.kind, role.value);
+      const back = parseMotionRoleValue(role.kind, text);
+      expect(back, `${role.id}: ${text}`).not.toBeNull();
+      if (role.kind === 'spring') {
+        const a = toSpring(role.value as Parameters<typeof toSpring>[0]);
+        const b = toSpring(back as Parameters<typeof toSpring>[0]);
+        expect(naturalFrequency(b) / naturalFrequency(a)).toBeCloseTo(1, 5);
+        expect(dampingRatioOf(b)).toBeCloseTo(dampingRatioOf(a), 5);
+      } else {
+        expect(back).toEqual(role.value);
+      }
+    }
+    expect(
+      formatMotionRoleValue('spring', {response: 0.5, dampingRatio: 0.85}),
+    ).toBe('0.5s 0.15');
+    expect(formatMotionRoleValue('duration', 250)).toBe('250ms');
+    expect(formatMotionRoleValue('curve', [0.42, 0, 0.58, 1])).toBe(
+      'cubic-bezier(0.42, 0, 0.58, 1)',
+    );
+  });
+
+  it('refuses invalid values and reads malformed CSS as unset', () => {
+    expect(() => formatMotionRoleValue('duration', -1)).toThrow(/≥ 0/);
+    expect(() => formatMotionRoleValue('curve', [2, 0, 0.5, 1])).toThrow(
+      /x1 and x2/,
+    );
+    expect(() => formatMotionRoleValue('spring', {response: 0.5})).toThrow(
+      /spring is/,
+    );
+    expect(parseMotionRoleValue('spring', '')).toBeNull();
+    expect(parseMotionRoleValue('spring', 'fast')).toBeNull();
+    expect(parseMotionRoleValue('spring', '0.4s 0.2')).toEqual({
+      duration: 0.4,
+      bounce: 0.2,
+    });
+    expect(parseMotionRoleValue('duration', ' 0.3s ')).toBe(300);
+    expect(parseMotionRoleValue('curve', 'ease-in')).toBeNull();
+  });
+});

package/src/motion/roles.ts

@@ -0,0 +1,262 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file roles.ts
+ * @input The motion tables (motion/uikit and each component's own table)
+ * @output registerMotionTable, motionRoleOf, motionRoleIn, listMotionRoles,
+ *   motionRoleVariable, and the CSS form of a role's value
+ *   (formatMotionRoleValue, parseMotionRoleValue)
+ * @position Motion foundation, internal to core: read by the code that
+ *   resolves a role when a motion starts. No public API writes a role: touch
+ *   motion stays internal until the public motion-token set is decided.
+ *
+ * A motion role is one value of a motion table: a
+ * spring, a duration (a key ending in `Ms`, in milliseconds) or a curve (four
+ * cubic-bézier control points). The roles are the ones `spec:AST-094` FR4
+ * names, each by its table path, such as `springs.settle` or
+ * `timing.curves.move`: a table lists its roles when it registers, and every
+ * other value, a component's measured spring included, stays an internal
+ * constant. No shipped component reads the roles yet.
+ * A role is carried by one CSS custom property, `--motion-` followed by its id
+ * in kebab case (`--motion-springs-settle`), which nothing public writes; an
+ * empty property means the table's value, so the table stays the one measured
+ * source of every value.
+ *
+ * Gesture thresholds, the velocity filter, the timings that decide who gets a
+ * touch and haptics are not motion: they are not roles (tables leave them out
+ * with `exclude`).
+ *
+ * SYNC: When modified, update /packages/core/src/motion/roles.test.ts.
+ */
+
+import {
+  formatMotionRoleValue,
+  isCurve,
+  isMotionRoleId,
+  isSpring,
+  motionRoleVariable,
+  type MotionCurvePoints,
+  type MotionRoleKind,
+} from './roleValue';
+import type {DurationBounce, SpringDescription} from './spring';
+
+export {formatMotionRoleValue, isMotionRoleId, motionRoleVariable};
+export type {MotionCurvePoints, MotionRoleKind};
+
+/** One registered role. */
+export interface MotionRole {
+  /** The table path, e.g. `springs.sheetDetent`. */
+  readonly id: string;
+  readonly kind: MotionRoleKind;
+  /** The CSS custom property that carries the role's value. */
+  readonly variable: string;
+  /** The table's value: what plays when the property is empty. */
+  readonly value: SpringDescription | number | MotionCurvePoints;
+}
+
+const rolesById = new Map<string, MotionRole>();
+/** A table id → the table registered under it. */
+const tablesById = new Map<string, object>();
+/** A spring or curve leaf → its role. */
+const roleOfLeaf = new WeakMap<object, MotionRole>();
+/** A table or one of its groups → its path. */
+const pathOfGroup = new WeakMap<object, string>();
+/** A table path → the role id it is registered under, when renamed. */
+const roleIdOfPath = new Map<string, string>();
+
+/**
+ * Registers a motion table: each spring, `…Ms` duration and curve leaf that
+ * `roles` lists (its role name, relative to the table) becomes a role named
+ * by its path under `id`; the table's other values stay internal constants. A leaf object the table shares between
+ * two keys is replaced in the table by an equal copy, so each role has its own
+ * object (an animator resolves a role from the object it is handed).
+ * `exclude` lists paths, relative to the table, that are not motion;
+ * `rename` maps a path, relative to the table, to the role name it is
+ * registered under (relative too), so a role is named for its use while the
+ * table keeps its source's name. Registering the same table under the same id
+ * again does nothing.
+ */
+export function registerMotionTable(
+  id: string,
+  table: object,
+  {
+    roles = [],
+    exclude = [],
+    rename = {},
+  }: {
+    roles?: ReadonlyArray<string>;
+    exclude?: ReadonlyArray<string>;
+    rename?: Readonly<Record<string, string>>;
+  } = {},
+): void {
+  if (!/^[a-z][A-Za-z0-9]*$/.test(id)) {
+    throw new Error(`motion table id "${id}" must be one camelCase word`);
+  }
+  // Registering the same table again changes nothing: each table's
+  // register function may run from every touch module that uses it.
+  if (tablesById.get(id) === table) {
+    return;
+  }
+  tablesById.set(id, table);
+  const skip = new Set(exclude.map(path => `${id}.${path}`));
+  const listed = new Set(roles.map(name => `${id}.${name}`));
+  const walk = (group: Record<string, unknown>, prefix: string) => {
+    pathOfGroup.set(group, prefix);
+    for (const [key, value] of Object.entries(group)) {
+      const path = `${prefix}.${key}`;
+      if (skip.has(path)) {
+        continue;
+      }
+      let kind: MotionRoleKind | null = null;
+      if (isSpring(value)) {
+        kind = 'spring';
+      } else if (isCurve(value)) {
+        kind = 'curve';
+      } else if (typeof value === 'number' && key.endsWith('Ms')) {
+        kind = 'duration';
+      } else if (
+        value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value)
+      ) {
+        walk(value as Record<string, unknown>, path);
+        continue;
+      }
+      if (kind == null) {
+        continue;
+      }
+      const relative = path.slice(id.length + 1);
+      const roleId = relative in rename ? `${id}.${rename[relative]}` : path;
+      // Only the roles the table lists; every other value stays internal.
+      if (!listed.has(roleId)) {
+        continue;
+      }
+      if (roleId !== path) {
+        roleIdOfPath.set(path, roleId);
+      }
+      let leaf = value as SpringDescription | number | MotionCurvePoints;
+      if (typeof leaf === 'object') {
+        const taken = roleOfLeaf.get(leaf);
+        if (taken != null && taken.id !== roleId) {
+          leaf = Object.freeze(Array.isArray(leaf) ? [...leaf] : {...leaf}) as
+            SpringDescription | MotionCurvePoints;
+          group[key] = leaf;
+        }
+      }
+      const role: MotionRole = {
+        id: roleId,
+        kind,
+        variable: motionRoleVariable(roleId),
+        value: leaf,
+      };
+      rolesById.set(roleId, role);
+      if (typeof leaf === 'object') {
+        roleOfLeaf.set(leaf, role);
+      }
+    }
+  };
+  walk(table as Record<string, unknown>, id);
+}
+
+/** The role a spring or curve leaf of a registered table plays, if any. */
+export function motionRoleOf(leaf: unknown): MotionRole | undefined {
+  return leaf !== null && typeof leaf === 'object'
+    ? roleOfLeaf.get(leaf)
+    : undefined;
+}
+
+/**
+ * The role `group[key]` plays, for a table or one of its groups: the way to
+ * name a duration, which is a bare number.
+ */
+export function motionRoleIn(
+  group: object,
+  key: string,
+): MotionRole | undefined {
+  const prefix = pathOfGroup.get(group);
+  if (prefix == null) {
+    return undefined;
+  }
+  const path = `${prefix}.${key}`;
+  return rolesById.get(roleIdOfPath.get(path) ?? path);
+}
+
+/** The role with this id, once its table is registered. */
+export function motionRole(id: string): MotionRole | undefined {
+  return rolesById.get(id);
+}
+
+/** Every registered role, by id. */
+export function listMotionRoles(): MotionRole[] {
+  return [...rolesById.values()].sort((a, b) => (a.id < b.id ? -1 : 1));
+}
+
+const NUMBER = '(-?(?:\\d+\\.?\\d*|\\.\\d+)(?:e-?\\d+)?)';
+const SPRING_VALUE = new RegExp(`^${NUMBER}s\\s+${NUMBER}$`);
+const DURATION_VALUE = new RegExp(`^${NUMBER}(ms|s)$`);
+const CURVE_VALUE = new RegExp(
+  `^cubic-bezier\\(\\s*${NUMBER}\\s*,\\s*${NUMBER}\\s*,\\s*${NUMBER}\\s*,\\s*${NUMBER}\\s*\\)$`,
+);
+
+/**
+ * Reads a role value back from its CSS custom property. Returns null for an
+ * empty or malformed value: the caller then uses the table's value.
+ */
+export function parseMotionRoleValue(
+  kind: 'spring',
+  text: string,
+): DurationBounce | null;
+export function parseMotionRoleValue(
+  kind: 'duration',
+  text: string,
+): number | null;
+export function parseMotionRoleValue(
+  kind: 'curve',
+  text: string,
+): MotionCurvePoints | null;
+export function parseMotionRoleValue(
+  kind: MotionRoleKind,
+  text: string,
+): DurationBounce | number | MotionCurvePoints | null;
+export function parseMotionRoleValue(
+  kind: MotionRoleKind,
+  text: string,
+): DurationBounce | number | MotionCurvePoints | null {
+  const value = text.trim();
+  if (value === '') {
+    return null;
+  }
+  if (kind === 'spring') {
+    const m = SPRING_VALUE.exec(value);
+    if (m == null) {
+      return null;
+    }
+    const duration = Number(m[1]);
+    const bounce = Number(m[2]);
+    // A bounce of 1 is undamped: it never settles.
+    return duration > 0 && bounce > -1 && bounce < 1
+      ? {duration, bounce}
+      : null;
+  }
+  if (kind === 'duration') {
+    const m = DURATION_VALUE.exec(value);
+    if (m == null) {
+      return null;
+    }
+    const ms = Number(m[1]) * (m[2] === 's' ? 1000 : 1);
+    return ms >= 0 ? ms : null;
+  }
+  const m = CURVE_VALUE.exec(value);
+  if (m == null) {
+    return null;
+  }
+  const points = [m[1], m[2], m[3], m[4]].map(Number) as unknown as [
+    number,
+    number,
+    number,
+    number,
+  ];
+  return points[0] >= 0 && points[0] <= 1 && points[2] >= 0 && points[2] <= 1
+    ? points
+    : null;
+}