react-native-layout-dnd 0.1.0-alpha.0

package/lib/typescript/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAa,CAAC;AAElE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAAyB,CAAC;AAElE,MAAM,MAAM,YAAY,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AACxD,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACtD,kFAAkF;AAClF,MAAM,MAAM,mBAAmB,GAC3B;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EACF,cAAc,GAAG,kBAAkB,GAAG,sBAAsB,GAAG,QAAQ,CAAC;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EACA,SAAS,GACT,mBAAmB,GACnB,SAAS,GACT,UAAU,GACV,UAAU,GACV,UAAU,GACV,KAAK,CAAC;IACV,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AACN,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,CAAC;AAClD,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,oFAAoF;IACpF,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,IAAI,EAAE,CAAC,CAAC;CACT,CAAC;AACF,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,EAAE,YAAY,CAAA;CAAE,CAAC;AAEzE,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;CAC5B,CAAC;AACF,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;CACtB,CAAC;AACF,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AAC1D,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACrB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,cAAc,CAAC,GAAG;QAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AACzE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,YAAY,CACxC,mBAAmB,CAAC,CAAC,CAAC,EACtB,YAAY,CACb,CAAC;AAEF,MAAM,MAAM,cAAc,GACtB,mBAAmB,GACnB,cAAc,GACd,mBAAmB,GACnB,cAAc,GACd,mBAAmB,GACnB,mBAAmB,GACnB,eAAe,GACf,kBAAkB,GAClB,eAAe,GACf,SAAS,GACT,mBAAmB,GACnB,gBAAgB,GAChB,kBAAkB,GAClB,uBAAuB,CAAC;AAC5B,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AACF,MAAM,MAAM,gBAAgB,GAC1B;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAChE,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAA;CAAE,GAC3C;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAChD,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,KAAK,EAAE,SAAS,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AACF,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAA;CAAE,GACjD;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAErD,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,GAC/D;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,mFAAmF;AACnF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,YAAY,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AACF,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IACE,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;IACnB,EAAE,EAAE,YAAY,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,GACD;IAAE,MAAM,EAAE,YAAY,GAAG,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;IACnB,EAAE,EAAE,YAAY,CAAC;CAClB,CAAC;AACF,MAAM,MAAM,cAAc,GAAG;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AACF,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI;IAC3B,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;CAC7B,CAAC;AACF,MAAM,MAAM,YAAY,GACtB;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAC1D,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,kBAAkB,GAClB,cAAc,GACd,UAAU,GACV,WAAW,CAAC;AAChB,gGAAgG;AAChG,MAAM,MAAM,uBAAuB,GACjC,YAAY,GAAG,kBAAkB,GAAG,sBAAsB,CAAC;AAC7D,MAAM,MAAM,YAAY,GACpB,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,GACf,cAAc,GACd,qBAAqB,GACrB,cAAc,GACd,qBAAqB,CAAC;AAC1B,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG;IAC1C,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,CACE;IAAE,OAAO,EAAE,WAAW,CAAA;CAAE,GACxB;IACE,OAAO,EAAE,WAAW,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACD,CAAC;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,CACjE;IAAE,QAAQ,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAA;CAAE,GAC9D;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,CAC/D,CAAC,CACL,CAAC"}

package/package.json

@@ -0,0 +1,136 @@
+{
+  "name": "react-native-layout-dnd",
+  "version": "0.1.0-alpha.0",
+  "description": "Drag and drop for React Native grids and lists: mixed spans, optional FlatList virtualization, and atomic moves between zones.",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "react-native-layout-dnd-source": "./src/index.ts",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./engine": {
+      "react-native-layout-dnd-source": "./src/engine/index.ts",
+      "types": "./lib/typescript/src/engine/index.d.ts",
+      "default": "./lib/module/engine/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-layout-dnd-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "build": "bob build",
+    "prepack": "bob build",
+    "test": "jest --runInBand --watchman=false",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "check:package": "node scripts/check-package.mjs",
+    "test:perf-tools": "node --test scripts/perf/metrics.test.mjs"
+  },
+  "keywords": [
+    "react-native",
+    "drag-and-drop",
+    "dnd",
+    "drag",
+    "drop",
+    "draggable",
+    "sortable",
+    "reorderable",
+    "grid",
+    "list",
+    "flatlist",
+    "reanimated",
+    "gesture-handler",
+    "ios",
+    "android"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baesumin/react-native-layout-dnd.git"
+  },
+  "author": {
+    "name": "baesumin",
+    "url": "https://github.com/baesumin"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/baesumin/react-native-layout-dnd/issues"
+  },
+  "homepage": "https://github.com/baesumin/react-native-layout-dnd#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@babel/core": "7.29.7",
+    "@eslint/compat": "^2.1.0",
+    "@eslint/eslintrc": "^3.3.6",
+    "@eslint/js": "^9.39.5",
+    "@react-native/babel-preset": "0.87.1",
+    "@react-native/eslint-config": "0.87.1",
+    "@react-native/jest-preset": "0.87.1",
+    "@react-native/metro-config": "0.87.1",
+    "@react-native/typescript-config": "0.87.1",
+    "@types/jest": "29.5.14",
+    "@types/react": "^19.2.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "jest": "29.7.0",
+    "prettier": "^3.9.6",
+    "react": "19.2.3",
+    "react-native": "0.87.1",
+    "react-native-builder-bob": "^0.43.1",
+    "react-native-gesture-handler": "3.3.0",
+    "react-native-reanimated": "4.6.0",
+    "react-native-worklets": "0.12.2",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-native": ">=0.78.0",
+    "react-native-gesture-handler": ">=3.0.0 <4.0.0",
+    "react-native-reanimated": ">=4.0.0 <5.0.0",
+    "react-native-worklets": ">=0.5.0 <1.0.0"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "prettier": {
+    "arrowParens": "avoid",
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "all",
+    "useTabs": false
+  }
+}

package/src/adapters/coordinates.ts

@@ -0,0 +1,181 @@
+import type {
+  CoordinateResult,
+  LayoutPoint,
+  LayoutRect,
+  MeasurementFreshness,
+  RectMeasurement,
+  ZoneCoordinateContext,
+} from '../contracts';
+
+import { isRecord } from '../engine/validation';
+
+function isPoint(value: unknown): value is LayoutPoint {
+  return (
+    isRecord(value) &&
+    typeof value.x === 'number' &&
+    Number.isFinite(value.x) &&
+    typeof value.y === 'number' &&
+    Number.isFinite(value.y)
+  );
+}
+
+function isRect(value: unknown): value is LayoutRect {
+  return (
+    isPoint(value) &&
+    'width' in value &&
+    typeof value.width === 'number' &&
+    Number.isFinite(value.width) &&
+    value.width > 0 &&
+    'height' in value &&
+    typeof value.height === 'number' &&
+    Number.isFinite(value.height) &&
+    value.height > 0
+  );
+}
+
+function isNonnegativeFinite(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+/** Estimates remain estimates after validation; callers must inspect source. */
+export function validateRectMeasurement<Measurement extends RectMeasurement>(
+  measurement: Measurement,
+  freshness: MeasurementFreshness,
+): CoordinateResult<Measurement> {
+  if (
+    !isRecord(freshness) ||
+    !Number.isSafeInteger(freshness.revision) ||
+    freshness.revision < 0 ||
+    (freshness.nowMs === undefined) !== (freshness.maxAgeMs === undefined) ||
+    (freshness.nowMs !== undefined &&
+      (!isNonnegativeFinite(freshness.nowMs) ||
+        !isNonnegativeFinite(freshness.maxAgeMs)))
+  ) {
+    return { valid: false, reason: 'invalid-freshness' };
+  }
+  if (
+    !isRecord(measurement) ||
+    (measurement.source !== 'measured' && measurement.source !== 'estimated') ||
+    (measurement.space !== 'screen' && measurement.space !== 'content') ||
+    !isRect(measurement.rect) ||
+    !Number.isSafeInteger(measurement.revision) ||
+    measurement.revision < 0 ||
+    !isNonnegativeFinite(measurement.timestampMs)
+  ) {
+    return { valid: false, reason: 'invalid-measurement' };
+  }
+  if (
+    measurement.revision !== freshness.revision ||
+    (freshness.nowMs !== undefined &&
+      (measurement.timestampMs > freshness.nowMs ||
+        freshness.nowMs - measurement.timestampMs > freshness.maxAgeMs!))
+  ) {
+    return { valid: false, reason: 'stale-measurement' };
+  }
+  return { valid: true, value: measurement };
+}
+
+function validateContext(
+  context: ZoneCoordinateContext,
+  freshness: MeasurementFreshness,
+): CoordinateResult<ZoneCoordinateContext> {
+  if (!isRecord(context) || !isPoint(context.scrollOffset)) {
+    return { valid: false, reason: 'invalid-context' };
+  }
+  const measurement = validateRectMeasurement(context.viewport, freshness);
+  if (!measurement.valid) return measurement;
+  if (
+    measurement.value.source !== 'measured' ||
+    measurement.value.space !== 'screen'
+  ) {
+    return { valid: false, reason: 'invalid-context' };
+  }
+  return { valid: true, value: context };
+}
+
+function convertPoint(
+  point: LayoutPoint,
+  context: ZoneCoordinateContext,
+  freshness: MeasurementFreshness,
+  direction: 'to-content' | 'to-screen',
+): CoordinateResult<LayoutPoint> {
+  if (!isPoint(point)) return { valid: false, reason: 'invalid-coordinate' };
+  const validation = validateContext(context, freshness);
+  if (!validation.valid) return validation;
+  const { rect } = context.viewport;
+  const { scrollOffset } = context;
+  const value =
+    direction === 'to-content'
+      ? {
+          x: point.x - rect.x + scrollOffset.x,
+          y: point.y - rect.y + scrollOffset.y,
+        }
+      : {
+          x: point.x - scrollOffset.x + rect.x,
+          y: point.y - scrollOffset.y + rect.y,
+        };
+  return isPoint(value)
+    ? { valid: true, value }
+    : { valid: false, reason: 'invalid-coordinate' };
+}
+
+/** Convert absolute screen pixels to zone content pixels using the current offset. */
+export function screenToContent(
+  point: LayoutPoint,
+  context: ZoneCoordinateContext,
+  freshness: MeasurementFreshness,
+): CoordinateResult<LayoutPoint> {
+  return convertPoint(point, context, freshness, 'to-content');
+}
+
+export function contentToScreen(
+  point: LayoutPoint,
+  context: ZoneCoordinateContext,
+  freshness: MeasurementFreshness,
+): CoordinateResult<LayoutPoint> {
+  return convertPoint(point, context, freshness, 'to-screen');
+}
+
+export function screenRectToContent(
+  measurement: RectMeasurement<'screen'>,
+  context: ZoneCoordinateContext,
+  freshness: MeasurementFreshness,
+): CoordinateResult<RectMeasurement<'content'>> {
+  const validation = validateRectMeasurement(measurement, freshness);
+  if (!validation.valid) return validation;
+  if (measurement.space !== 'screen')
+    return { valid: false, reason: 'invalid-measurement' };
+  const converted = screenToContent(measurement.rect, context, freshness);
+  return converted.valid
+    ? {
+        valid: true,
+        value: {
+          ...measurement,
+          space: 'content',
+          rect: { ...measurement.rect, ...converted.value },
+        },
+      }
+    : converted;
+}
+
+export function contentRectToScreen(
+  measurement: RectMeasurement<'content'>,
+  context: ZoneCoordinateContext,
+  freshness: MeasurementFreshness,
+): CoordinateResult<RectMeasurement<'screen'>> {
+  const validation = validateRectMeasurement(measurement, freshness);
+  if (!validation.valid) return validation;
+  if (measurement.space !== 'content')
+    return { valid: false, reason: 'invalid-measurement' };
+  const converted = contentToScreen(measurement.rect, context, freshness);
+  return converted.valid
+    ? {
+        valid: true,
+        value: {
+          ...measurement,
+          space: 'screen',
+          rect: { ...measurement.rect, ...converted.value },
+        },
+      }
+    : converted;
+}

package/src/adapters/scroll.ts

@@ -0,0 +1,147 @@
+import type { LayoutPoint } from '../contracts';
+
+/** The permitted drag direction is independent of a list's orientation. */
+export type DragAxis = 'x' | 'y' | 'both';
+
+export type AutoScrollOptions = {
+  enabled?: boolean;
+  /** Edge activation distance in logical pixels. Defaults to 48. */
+  edgeThreshold?: number;
+  /** Maximum speed in logical pixels per second. Defaults to 600. */
+  maxSpeed?: number;
+};
+
+/** One axis of a measured scroll viewport, using logical pixels throughout. */
+export type AutoScrollInput = {
+  /** Absolute screen coordinate on the scrolling axis. */
+  pointer: number;
+  viewportStart: number;
+  viewportSize: number;
+  /** Current native scroll offset; temporary bounce offsets are accepted. */
+  offset: number;
+  contentSize: number;
+  deltaTimeMs: number;
+  options?: AutoScrollOptions;
+};
+
+export type AutoScrollResult =
+  | {
+      valid: true;
+      /** Bounded native scroll target, including when velocity is zero. */
+      offset: number;
+      /** Actual speed after clamping, in logical pixels per second. */
+      velocity: number;
+    }
+  | { valid: false; reason: 'invalid-input' | 'invalid-options' };
+
+export type AutoScrollOptionsValidationResult =
+  { valid: true } | { valid: false; reason: 'invalid-options' };
+
+/** Validate public options before activating a gesture or executing a frame. */
+export function validateAutoScrollOptions(
+  options?: AutoScrollOptions,
+): AutoScrollOptionsValidationResult {
+  'worklet';
+  if (
+    options !== undefined &&
+    (!options ||
+      typeof options !== 'object' ||
+      Array.isArray(options) ||
+      (options.enabled !== undefined && typeof options.enabled !== 'boolean') ||
+      (options.edgeThreshold !== undefined &&
+        (!Number.isFinite(options.edgeThreshold) ||
+          options.edgeThreshold <= 0)) ||
+      (options.maxSpeed !== undefined &&
+        (!Number.isFinite(options.maxSpeed) || options.maxSpeed < 0)))
+  )
+    return { valid: false, reason: 'invalid-options' };
+  return { valid: true };
+}
+
+/**
+ * Compute one frame of edge scrolling for either orientation. Adapters should
+ * call scrollTo only for nonzero velocity, preserving native bounce while idle.
+ * Call only during an active drag, and re-read its candidate after scrolling.
+ */
+export function computeAutoScroll(input: AutoScrollInput): AutoScrollResult {
+  'worklet';
+  if (
+    !input ||
+    typeof input !== 'object' ||
+    Array.isArray(input) ||
+    !Number.isFinite(input.pointer) ||
+    !Number.isFinite(input.viewportStart) ||
+    !Number.isFinite(input.viewportSize) ||
+    input.viewportSize <= 0 ||
+    !Number.isFinite(input.offset) ||
+    !Number.isFinite(input.contentSize) ||
+    input.contentSize < 0 ||
+    !Number.isFinite(input.deltaTimeMs) ||
+    input.deltaTimeMs < 0
+  )
+    return { valid: false, reason: 'invalid-input' };
+
+  const { options } = input;
+  const validation = validateAutoScrollOptions(options);
+  if (!validation.valid) return validation;
+
+  const maximum = Math.max(0, input.contentSize - input.viewportSize);
+  const offset = Math.max(0, Math.min(maximum, input.offset));
+  const idle: AutoScrollResult = { valid: true, offset, velocity: 0 };
+  const pointer = input.pointer - input.viewportStart;
+  if (!Number.isFinite(pointer))
+    return { valid: false, reason: 'invalid-input' };
+
+  if (
+    options?.enabled === false ||
+    pointer < 0 ||
+    pointer > input.viewportSize ||
+    maximum === 0 ||
+    input.deltaTimeMs === 0
+  )
+    return idle;
+
+  // Cap overlapping edge bands at the midpoint so tiny viewports do not bias
+  // toward the first edge. The exact midpoint has no preferred direction.
+  const threshold = Math.min(
+    options?.edgeThreshold ?? 48,
+    input.viewportSize / 2,
+  );
+  if (threshold === 0) return idle;
+  const trailingDistance = input.viewportSize - pointer;
+  const direction =
+    pointer < threshold ? -1 : trailingDistance < threshold ? 1 : 0;
+  if (direction === 0) return idle;
+
+  const distance = direction < 0 ? pointer : trailingDistance;
+  const speed = (options?.maxSpeed ?? 600) * (1 - distance / threshold);
+  // A paused/resumed frame must not skip a large portion of the list.
+  const seconds = Math.min(input.deltaTimeMs, 64) / 1000;
+  if (seconds === 0 || speed === 0) return idle;
+  const nextOffset = Math.max(
+    0,
+    Math.min(maximum, offset + direction * speed * seconds),
+  );
+  const movement = nextOffset - offset;
+  return {
+    valid: true,
+    offset: nextOffset,
+    velocity:
+      movement === 0
+        ? 0
+        : direction * Math.min(speed, Math.abs(movement / seconds)),
+  };
+}
+
+/** Project a validated screen point onto the configured axis through origin. */
+export function constrainDragPoint(
+  point: LayoutPoint,
+  origin: LayoutPoint,
+  axis: DragAxis,
+): LayoutPoint {
+  'worklet';
+  return {
+    x: axis === 'y' ? origin.x : point.x,
+    y: axis === 'x' ? origin.y : point.y,
+  };
+}

package/src/adapters/virtualizedList.ts

@@ -0,0 +1,112 @@
+import type { LayoutValidationIssue } from '../contracts';
+import { isPositiveInteger, isRecord } from '../engine/validation';
+
+/** FlatList rendering limits; enabling virtualization preserves the layout API. */
+export type ListVirtualizationOptions = {
+  /** Cells rendered initially. Defaults to 12. */
+  initialNumToRender?: number;
+  /** Maximum cells rendered in each batch. Defaults to 12. */
+  maxToRenderPerBatch?: number;
+  /** Render window in viewport lengths; must exceed 1. Defaults to 7. */
+  windowSize?: number;
+  /** Delay between render batches in milliseconds. Defaults to 50. */
+  updateCellsBatchingPeriod?: number;
+};
+
+export type ListVirtualizationResult =
+  | { valid: true; options: Required<ListVirtualizationOptions> | null }
+  | { valid: false; issues: LayoutValidationIssue[] };
+
+const DEFAULT_OPTIONS: Readonly<Required<ListVirtualizationOptions>> =
+  Object.freeze({
+    initialNumToRender: 12,
+    maxToRenderPerBatch: 12,
+    windowSize: 7,
+    updateCellsBatchingPeriod: 50,
+  });
+
+function invalid(message: string): ListVirtualizationResult {
+  return {
+    valid: false,
+    issues: [{ code: 'invalid-configuration', message }],
+  };
+}
+
+/** Undefined/false selects ScrollView; true or an options object selects FlatList. */
+export function resolveListVirtualization(
+  value: unknown,
+): ListVirtualizationResult {
+  if (value === undefined || value === false) {
+    return { valid: true, options: null };
+  }
+  if (value === true) return { valid: true, options: { ...DEFAULT_OPTIONS } };
+  if (!isRecord(value)) {
+    return invalid('virtualization must be a boolean or an options object.');
+  }
+  if (
+    Object.keys(value).some(
+      key =>
+        key !== 'initialNumToRender' &&
+        key !== 'maxToRenderPerBatch' &&
+        key !== 'windowSize' &&
+        key !== 'updateCellsBatchingPeriod',
+    )
+  ) {
+    return invalid(
+      'virtualization supports only initialNumToRender, maxToRenderPerBatch, windowSize and updateCellsBatchingPeriod.',
+    );
+  }
+  const initialNumToRender =
+    value.initialNumToRender === undefined
+      ? DEFAULT_OPTIONS.initialNumToRender
+      : value.initialNumToRender;
+  const maxToRenderPerBatch =
+    value.maxToRenderPerBatch === undefined
+      ? DEFAULT_OPTIONS.maxToRenderPerBatch
+      : value.maxToRenderPerBatch;
+  const windowSize =
+    value.windowSize === undefined
+      ? DEFAULT_OPTIONS.windowSize
+      : value.windowSize;
+  const updateCellsBatchingPeriod =
+    value.updateCellsBatchingPeriod === undefined
+      ? DEFAULT_OPTIONS.updateCellsBatchingPeriod
+      : value.updateCellsBatchingPeriod;
+  if (!isPositiveInteger(initialNumToRender)) {
+    return invalid(
+      'virtualization.initialNumToRender must be a positive safe integer.',
+    );
+  }
+  if (!isPositiveInteger(maxToRenderPerBatch)) {
+    return invalid(
+      'virtualization.maxToRenderPerBatch must be a positive safe integer.',
+    );
+  }
+  if (
+    typeof windowSize !== 'number' ||
+    !Number.isFinite(windowSize) ||
+    windowSize <= 1
+  ) {
+    return invalid(
+      'virtualization.windowSize must be finite and greater than 1.',
+    );
+  }
+  if (
+    typeof updateCellsBatchingPeriod !== 'number' ||
+    !Number.isFinite(updateCellsBatchingPeriod) ||
+    updateCellsBatchingPeriod < 0
+  ) {
+    return invalid(
+      'virtualization.updateCellsBatchingPeriod must be finite and nonnegative.',
+    );
+  }
+  return {
+    valid: true,
+    options: {
+      initialNumToRender,
+      maxToRenderPerBatch,
+      windowSize,
+      updateCellsBatchingPeriod,
+    },
+  };
+}