@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/motion/uikit/scroll.d.ts

@@ -0,0 +1,116 @@
+export declare const DELAYS_CONTENT_TOUCHES_MS = 150;
+export declare const scroll: {
+    readonly decelerationRate: {
+        /**
+         * Normal deceleration: the release velocity is multiplied by this every
+         * millisecond, as a continuous exponential (UIScrollView keeps ln r,
+         * −0.002002, and velocities in pt/ms). The scroll view's own
+         * target for a release (`scrollViewWillEndDragging`) is
+         * v · r ÷ (1 − r), within 1 %: WWDC18 803's projection function.
+         * @source apple-docs https://developer.apple.com/documentation/uikit/uiscrollview/decelerationrate-swift.struct/normal
+         *   (the constant, not its number)
+         * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+         *   iPhone 17 Pro, rawValue read, Oct 23 2026 (also a new scroll view's
+         *   decelerationRate)
+         * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+         *   iPhone 17 Pro, deceleration ivars read mid-coast
+         *   (`_decelerationFactor` 0.998, `_decelerationLnFactorV` −0.002002, the
+         *   velocity decaying 0.4343 over 400 ms) and willEndDragging targets,
+         *   Oct 23 2026
+         */
+        readonly normal: 0.998;
+        /**
+         * Fast deceleration (`UIScrollView.DecelerationRate.fast`).
+         * @source apple-docs https://developer.apple.com/documentation/uikit/uiscrollview/decelerationrate-swift.struct/fast
+         *   (the constant, not its number)
+         * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+         *   iPhone 17 Pro, rawValue read and `_decelerationFactor` 0.99 (ln
+         *   −0.01005) mid-coast, Oct 23 2026
+         */
+        readonly fast: 0.99;
+    };
+    readonly rubberBand: {
+        /**
+         * c in b = (1 − 1 ÷ (x·c ÷ d + 1))·d, d = the scroll view's size on the
+         * axis, x = the finger's travel past the edge after the
+         * pan's 10 pt hysteresis.
+         * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+         *   iPhone 17 Pro, UIScrollView offsets released 100 / 300 / 600 pt past
+         *   the edge of an 874 pt view: 47 / 135 / 236.67 against the formula's
+         *   46.85 / 134.9 / 236.6, Oct 23 2026
+         * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+         *   iPhone 17 Pro, sheet drags hooked: UISheetPresentationController
+         *   passes `withRubberBandCoefficient: 0.55` on every drag, Oct 23 2026
+         */
+        readonly coefficient: 0.55;
+    };
+    /**
+     * The spring that returns content released past an edge, and that catches
+     * a coast hitting an edge (its velocity handed to the spring).
+     * @source GUESS — critically damped as in I. Lobanov's UIScrollView
+     *   reimplementation (no oscillation at the bound); pace from SwiftUI's
+     *   `.smooth` default duration. Measured so far (iOS 26.2 simulator, Oct 23
+     *   2026): back to the edge in about 0.5 s with no overshoot, but no single
+     *   spring from rest fits releases 47, 135 and 237 pt past the edge, so
+     *   UIKit's bounce is not a plain spring; the model is still to fit
+     * @measure M-S3
+     */
+    readonly bounce: {
+        readonly duration: 0.5;
+        readonly bounce: 0;
+    };
+    readonly paging: {
+        /**
+         * Deceleration rate a paging release is projected with to pick the next
+         * page.
+         * @source GUESS — UIScrollView paging behaves like a fast scroll view;
+         *   the rate it uses internally is not documented
+         * @measure M-PG1
+         */
+        readonly projectionRate: 0.99;
+        /**
+         * The spring that carries a paging scroll view onto its page.
+         * @source GUESS — SwiftUI `.smooth` default until measured
+         * @measure M-PG1
+         */
+        readonly snap: {
+            readonly duration: 0.5;
+            readonly bounce: 0;
+        };
+    };
+    /**
+     * `delaysContentTouches`: how long a scroll view holds a touch-down from
+     * its content while it decides whether the touch is a scroll (no highlight
+     * flash on a quick scroll), in ms.
+     * @source wwdc 2014-235 "Advanced Scrollviews and Touch Handling
+     *   Techniques": the touch-delay recognizer UIScrollView uses runs "a
+     *   pretty short timer … Let's say .15 seconds" (presenter's example value)
+     * @source measured: Settings and Contacts, iOS 26.2, simulator driven with
+     *   real HID touches at 60 fps, recorded with the touch press model
+     *   (PRESS_ONSET_MS in packages/core/src/utils/pressGesture.ts, 2026-10-06)
+     */
+    readonly delaysContentTouchesMs: 150;
+    /**
+     * Scroll-to-top after a status-bar tap: not a spring. The offset
+     * approaches the top as 1 − e^(−9.7 t) whatever the distance (done in about
+     * 1.6 s for 500, 2000 or 8000 pt), which is a decay at this per-millisecond
+     * rate (e^(−0.0097)) whose rest point is the top: a decay with a
+     * starting velocity of 9.7 × the distance per second. A tap starts it, not
+     * a throw, so under Reduce Motion it is a transition, not a coast: it
+     * cross-fades to the top within 200 ms on a coarse pointer (DR2) and jumps
+     * there on any other (DR3). Only momentum that continues a throw keeps
+     * decaying under Reduce Motion (`design:reduced-motion` DR2, DEC-2), so a
+     * component checks for Reduce Motion before it plays this decay.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, setContentOffset log after status-bar taps (starts 85–95
+     *   ms after the tap), Oct 23 2026
+     */
+    readonly scrollToTopRate: 0.99035;
+};
+/**
+ * Registers this table with the motion registry (motion/roles.ts). It lists
+ * no role: spec:AST-094 FR4 names none of its values, so each plays as
+ * measured. Nothing registers on import, and a second call does nothing.
+ */
+export declare function registerScrollTable(): void;
+//# sourceMappingURL=scroll.d.ts.map

package/dist/motion/uikit/scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll.d.ts","sourceRoot":"","sources":["../../../src/motion/uikit/scroll.ts"],"names":[],"mappings":"AAyBA,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,eAAO,MAAM,MAAM;;QAEf;;;;;;;;;;;;;;;;WAgBG;;QAEH;;;;;;;WAOG;;;;QAIH;;;;;;;;;;;WAWG;;;IAGL;;;;;;;;;;OAUG;;;;;;QAGD;;;;;;WAMG;;QAEH;;;;WAIG;;;;;;IAGL;;;;;;;;;;OAUG;;IAEH;;;;;;;;;;;;;;OAcG;;CAEK,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C"}

package/dist/motion/uikit/scroll.js

@@ -0,0 +1,146 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file scroll.ts
+ * @input Nothing; data only
+ * @output Exports `scroll`, the UIScrollView constants: deceleration rates,
+ *   the rubber-band coefficient, the bounce-back spring, paging and the
+ *   content-touch delay
+ * @position The scroll domain of the UIKit constants table (motion/uikit);
+ *   read by the motion math and components
+ *
+ * Every leaf carries one `@source` (apple-docs | wwdc | webkit | measured |
+ * GUESS); webkit and GUESS values also carry the `@measure` task that will
+ * confirm or replace them (listed in MEASUREMENTS.md). uikit.test.ts
+ * enforces both.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/MEASUREMENTS.md (measurement tasks)
+ */
+
+import { registerMotionTable } from "../roles.js";
+
+// The value of `scroll.delaysContentTouchesMs` (sourced there), its own
+// export so the press clocks read it without the rest of the table
+// (`architecture:component-style-authoring` INV6).
+export const DELAYS_CONTENT_TOUCHES_MS = 150;
+export const scroll = {
+  decelerationRate: {
+    /**
+     * Normal deceleration: the release velocity is multiplied by this every
+     * millisecond, as a continuous exponential (UIScrollView keeps ln r,
+     * −0.002002, and velocities in pt/ms). The scroll view's own
+     * target for a release (`scrollViewWillEndDragging`) is
+     * v · r ÷ (1 − r), within 1 %: WWDC18 803's projection function.
+     * @source apple-docs https://developer.apple.com/documentation/uikit/uiscrollview/decelerationrate-swift.struct/normal
+     *   (the constant, not its number)
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, rawValue read, Oct 23 2026 (also a new scroll view's
+     *   decelerationRate)
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, deceleration ivars read mid-coast
+     *   (`_decelerationFactor` 0.998, `_decelerationLnFactorV` −0.002002, the
+     *   velocity decaying 0.4343 over 400 ms) and willEndDragging targets,
+     *   Oct 23 2026
+     */
+    normal: 0.998,
+    /**
+     * Fast deceleration (`UIScrollView.DecelerationRate.fast`).
+     * @source apple-docs https://developer.apple.com/documentation/uikit/uiscrollview/decelerationrate-swift.struct/fast
+     *   (the constant, not its number)
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, rawValue read and `_decelerationFactor` 0.99 (ln
+     *   −0.01005) mid-coast, Oct 23 2026
+     */
+    fast: 0.99
+  },
+  rubberBand: {
+    /**
+     * c in b = (1 − 1 ÷ (x·c ÷ d + 1))·d, d = the scroll view's size on the
+     * axis, x = the finger's travel past the edge after the
+     * pan's 10 pt hysteresis.
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, UIScrollView offsets released 100 / 300 / 600 pt past
+     *   the edge of an 874 pt view: 47 / 135 / 236.67 against the formula's
+     *   46.85 / 134.9 / 236.6, Oct 23 2026
+     * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+     *   iPhone 17 Pro, sheet drags hooked: UISheetPresentationController
+     *   passes `withRubberBandCoefficient: 0.55` on every drag, Oct 23 2026
+     */
+    coefficient: 0.55
+  },
+  /**
+   * The spring that returns content released past an edge, and that catches
+   * a coast hitting an edge (its velocity handed to the spring).
+   * @source GUESS — critically damped as in I. Lobanov's UIScrollView
+   *   reimplementation (no oscillation at the bound); pace from SwiftUI's
+   *   `.smooth` default duration. Measured so far (iOS 26.2 simulator, Oct 23
+   *   2026): back to the edge in about 0.5 s with no overshoot, but no single
+   *   spring from rest fits releases 47, 135 and 237 pt past the edge, so
+   *   UIKit's bounce is not a plain spring; the model is still to fit
+   * @measure M-S3
+   */
+  bounce: {
+    duration: 0.5,
+    bounce: 0
+  },
+  paging: {
+    /**
+     * Deceleration rate a paging release is projected with to pick the next
+     * page.
+     * @source GUESS — UIScrollView paging behaves like a fast scroll view;
+     *   the rate it uses internally is not documented
+     * @measure M-PG1
+     */
+    projectionRate: 0.99,
+    /**
+     * The spring that carries a paging scroll view onto its page.
+     * @source GUESS — SwiftUI `.smooth` default until measured
+     * @measure M-PG1
+     */
+    snap: {
+      duration: 0.5,
+      bounce: 0
+    }
+  },
+  /**
+   * `delaysContentTouches`: how long a scroll view holds a touch-down from
+   * its content while it decides whether the touch is a scroll (no highlight
+   * flash on a quick scroll), in ms.
+   * @source wwdc 2014-235 "Advanced Scrollviews and Touch Handling
+   *   Techniques": the touch-delay recognizer UIScrollView uses runs "a
+   *   pretty short timer … Let's say .15 seconds" (presenter's example value)
+   * @source measured: Settings and Contacts, iOS 26.2, simulator driven with
+   *   real HID touches at 60 fps, recorded with the touch press model
+   *   (PRESS_ONSET_MS in packages/core/src/utils/pressGesture.ts, 2026-10-06)
+   */
+  delaysContentTouchesMs: DELAYS_CONTENT_TOUCHES_MS,
+  /**
+   * Scroll-to-top after a status-bar tap: not a spring. The offset
+   * approaches the top as 1 − e^(−9.7 t) whatever the distance (done in about
+   * 1.6 s for 500, 2000 or 8000 pt), which is a decay at this per-millisecond
+   * rate (e^(−0.0097)) whose rest point is the top: a decay with a
+   * starting velocity of 9.7 × the distance per second. A tap starts it, not
+   * a throw, so under Reduce Motion it is a transition, not a coast: it
+   * cross-fades to the top within 200 ms on a coarse pointer (DR2) and jumps
+   * there on any other (DR3). Only momentum that continues a throw keeps
+   * decaying under Reduce Motion (`design:reduced-motion` DR2, DEC-2), so a
+   * component checks for Reduce Motion before it plays this decay.
+   * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,
+   *   iPhone 17 Pro, setContentOffset log after status-bar taps (starts 85–95
+   *   ms after the tap), Oct 23 2026
+   */
+  scrollToTopRate: 0.99035
+};
+
+/**
+ * Registers this table with the motion registry (motion/roles.ts). It lists
+ * no role: spec:AST-094 FR4 names none of its values, so each plays as
+ * measured. Nothing registers on import, and a second call does nothing.
+ */
+export function registerScrollTable() {
+  registerMotionTable('scroll', scroll, {
+    // Arbitration: who gets the touch, not how anything moves.
+    exclude: ['delaysContentTouchesMs']
+  });
+}