@astryxdesign/lab 0.7.9-canary.2ea8f68 → 0.7.9-canary.4e7823a

package/dist/RefreshControl/RefreshPullRecognizer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file RefreshPullRecognizer.ts
+ * @input Touches from the gesture arena (Core's internal touch entry)
+ * @output Exports RefreshPullRecognizer, the vertical pan that reads a pull
+ *   to refresh without taking the touch, and RefreshScrollPullRecognizer
+ * @position The gesture of useRefreshControl, on the foundation's
+ *   PanGestureRecognizer
+ *
+ * SYNC: When modified, update:
+ * - /packages/lab/src/RefreshControl/useRefreshControl.ts
+ */
+import { PanGestureRecognizer, type PanGestureRecognizerOptions } from '@astryxdesign/core/internal/touch';
+import type { GestureEventContext, GestureTouch, PointerKind } from '@astryxdesign/core/internal/touch';
+export declare class RefreshPullRecognizer extends PanGestureRecognizer {
+    /** Called when the first contact of a gesture lands, with its timestamp. */
+    onTouchDown: ((time: number) => void) | null;
+    /** The pointer of the gesture's first contact. */
+    pointerType: PointerKind;
+    /** Set when the gesture is a trackpad's scroll rather than a contact. */
+    scrollType: GestureTouch['scrollType'] | null;
+    constructor(options?: PanGestureRecognizerOptions);
+    /** Native scrolling keeps the finger: the pull only reads it. */
+    get claimsTouches(): boolean;
+    protected touchesBegan(touches: ReadonlyArray<GestureTouch>, event: GestureEventContext): void;
+}
+/**
+ * The scroll pull: a trackpad's two-finger scroll at the top. It is a
+ * scroll-edge pan that takes a trackpad's scroll and no pointer. So it takes a
+ * scroll only where nothing under the pointer could scroll: the owner at its
+ * top and the content moving down. The host cancels each wheel event of a
+ * gesture that it takes, so its element gets a blocking `wheel` listener. Only
+ * a recognizer that claims may register one. It takes no pointer, so it adds
+ * no `touchmove` listener.
+ */
+export declare class RefreshScrollPullRecognizer extends RefreshPullRecognizer {
+    constructor(options?: PanGestureRecognizerOptions);
+    /** The scroll it takes is its own: the host cancels its wheel events. */
+    get claimsTouches(): boolean;
+}
+//# sourceMappingURL=RefreshPullRecognizer.d.ts.map

package/dist/RefreshControl/RefreshPullRecognizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RefreshPullRecognizer.d.ts","sourceRoot":"","sources":["../../src/RefreshControl/RefreshPullRecognizer.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAoBH,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,EACjC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACZ,WAAW,EACZ,MAAM,mCAAmC,CAAC;AAE3C,qBAAa,qBAAsB,SAAQ,oBAAoB;IAC7D,4EAA4E;IAC5E,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IACpD,kDAAkD;IAClD,WAAW,EAAE,WAAW,CAAW;IACnC,yEAAyE;IACzE,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,GAAG,IAAI,CAAQ;gBAEzC,OAAO,GAAE,2BAAgC;IAUrD,iEAAiE;IACjE,IAAa,aAAa,IAAI,OAAO,CAEpC;cAEkB,YAAY,CAC7B,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,KAAK,EAAE,mBAAmB,GACzB,IAAI;CASR;AAED;;;;;;;;GAQG;AACH,qBAAa,2BAA4B,SAAQ,qBAAqB;gBACxD,OAAO,GAAE,2BAAgC;IAUrD,yEAAyE;IACzE,IAAa,aAAa,IAAI,OAAO,CAEpC;CACF"}

package/dist/RefreshControl/RefreshPullRecognizer.js

@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file RefreshPullRecognizer.ts
+ * @input Touches from the gesture arena (Core's internal touch entry)
+ * @output Exports RefreshPullRecognizer, the vertical pan that reads a pull
+ *   to refresh without taking the touch, and RefreshScrollPullRecognizer
+ * @position The gesture of useRefreshControl, on the foundation's
+ *   PanGestureRecognizer
+ *
+ * SYNC: When modified, update:
+ * - /packages/lab/src/RefreshControl/useRefreshControl.ts
+ */
+
+// UIKit's refresh pull is the scroll view's own drag, not a second gesture.
+// One touch can scroll, pull past the top, and scroll the same content again.
+// So this pan never claims its touch, and only watches it. The browser keeps
+// the finger for native scrolling, so nothing changes hands midway. The pan
+// reads the finger to draw the overscroll, because the scroll owner's
+// `overscroll-behavior-y` is `none` near the top.
+//
+// The pan begins on vertical travel past its hysteresis. The touch layer
+// starts the pull where the content is at its top and the finger moves down.
+// When the browser takes the touch to scroll, the pan keeps reading it to the
+// lift. A second finger is the browser's, for pinch-zoom.
+//
+// A trackpad's scroll pulls through RefreshScrollPullRecognizer. A pen's or
+// a mouse's drag stays the browser's, for text selection: the pan takes only
+// a finger. `pointerType` and `scrollType` record the first contact's input.
+// `onTouchDown` reports that contact landing, so a settle in flight can stop
+// where it is, as UIScrollView brakes on touch-down.
+
+import { PanGestureRecognizer } from '@astryxdesign/core/internal/touch';
+export class RefreshPullRecognizer extends PanGestureRecognizer {
+  /** Called when the first contact of a gesture lands, with its timestamp. */
+  onTouchDown = null;
+  /** The pointer of the gesture's first contact. */
+  pointerType = 'touch';
+  /** Set when the gesture is a trackpad's scroll rather than a contact. */
+  scrollType = null;
+  constructor(options = {}) {
+    super({
+      name: 'RefreshPull',
+      direction: 'vertical',
+      maximumNumberOfTouches: 1,
+      allowedPointerTypes: ['touch'],
+      ...options
+    });
+  }
+
+  /** Native scrolling keeps the finger: the pull only reads it. */
+  get claimsTouches() {
+    return false;
+  }
+  touchesBegan(touches, event) {
+    if (this.numberOfTouches === touches.length) {
+      const touch = touches[0];
+      this.pointerType = touch?.pointerType ?? 'touch';
+      this.scrollType = touch?.scrollType ?? null;
+      this.onTouchDown?.(event.time);
+    }
+    super.touchesBegan(touches, event);
+  }
+}
+
+/**
+ * The scroll pull: a trackpad's two-finger scroll at the top. It is a
+ * scroll-edge pan that takes a trackpad's scroll and no pointer. So it takes a
+ * scroll only where nothing under the pointer could scroll: the owner at its
+ * top and the content moving down. The host cancels each wheel event of a
+ * gesture that it takes, so its element gets a blocking `wheel` listener. Only
+ * a recognizer that claims may register one. It takes no pointer, so it adds
+ * no `touchmove` listener.
+ */
+export class RefreshScrollPullRecognizer extends RefreshPullRecognizer {
+  constructor(options = {}) {
+    super({
+      name: 'RefreshScrollPull',
+      scrollEdge: true,
+      allowedPointerTypes: [],
+      allowedScrollTypes: ['continuous'],
+      ...options
+    });
+  }
+
+  /** The scroll it takes is its own: the host cancels its wheel events. */
+  get claimsTouches() {
+    return true;
+  }
+}

package/dist/RefreshControl/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @file index.ts
+ * @input Imports from useRefreshControl
+ * @output Exports useRefreshControl, its types and the reveal's custom
+ *   property
+ * @position Entry point for Lab's pull to refresh; re-exported by
+ *   /packages/lab/src/index.ts
+ */
+export { REFRESH_REVEAL_VAR, useRefreshControl } from './useRefreshControl.js';
+export type { UseRefreshControlOptions, UseRefreshControlResult, } from './useRefreshControl.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/RefreshControl/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/RefreshControl/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,kBAAkB,EAAE,iBAAiB,EAAC,MAAM,qBAAqB,CAAC;AAC1E,YAAY,EACV,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC"}

package/dist/RefreshControl/index.js

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from useRefreshControl
+ * @output Exports useRefreshControl, its types and the reveal's custom
+ *   property
+ * @position Entry point for Lab's pull to refresh; re-exported by
+ *   /packages/lab/src/index.ts
+ */
+export { REFRESH_REVEAL_VAR, useRefreshControl } from "./useRefreshControl.js";

package/dist/RefreshControl/refreshIndicator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file refreshIndicator.ts
+ * @output The name of the custom property the touch layer writes and the
+ *   app's indicator styles may read
+ * @position Internal to useRefreshControl; re-exported for the app's
+ *   indicator styles
+ */
+/** CSS custom property the indicator reads: how much of it is revealed (0–1). */
+export declare const REFRESH_REVEAL_VAR = "--astryx-refresh-reveal";
+//# sourceMappingURL=refreshIndicator.d.ts.map

package/dist/RefreshControl/refreshIndicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshIndicator.d.ts","sourceRoot":"","sources":["../../src/RefreshControl/refreshIndicator.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,4BAA4B,CAAC"}

package/dist/RefreshControl/refreshIndicator.js

@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file refreshIndicator.ts
+ * @output The name of the custom property the touch layer writes and the
+ *   app's indicator styles may read
+ * @position Internal to useRefreshControl; re-exported for the app's
+ *   indicator styles
+ */
+
+/** CSS custom property the indicator reads: how much of it is revealed (0–1). */
+export const REFRESH_REVEAL_VAR = '--astryx-refresh-reveal';

package/dist/RefreshControl/refreshModel.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @file refreshModel.ts
+ * @input Pull events from the refresh pull recognizer, and programmatic begin
+ *   and end requests
+ * @output Exports reduceRefresh (UIRefreshControl's state machine as a pure
+ *   reducer that returns the effects to run), the initial state and types
+ * @position Pure logic for useRefreshControl; no DOM, no React
+ *
+ * SYNC: When modified, update:
+ * - /packages/lab/src/RefreshControl/refreshModel.test.ts
+ */
+export interface RefreshState {
+    /** A refresh is in progress (`UIRefreshControl.isRefreshing`). */
+    readonly isRefreshing: boolean;
+    /** A finger is pulling the content. */
+    readonly isPulling: boolean;
+    /** The current pull has triggered (its mapping turns one to one). */
+    readonly hasTriggered: boolean;
+}
+export type RefreshEvent = {
+    readonly type: 'pullStart';
+} | {
+    readonly type: 'pullMove';
+    readonly overscroll: number;
+    /** The trigger distance for this scroll owner. */
+    readonly trigger: number;
+} | {
+    readonly type: 'pullEnd';
+} | {
+    readonly type: 'pullCancel';
+} | {
+    readonly type: 'begin';
+    readonly source: 'user' | 'program';
+} | {
+    readonly type: 'end';
+};
+export type RefreshEffect = 
+/** The pull reached the trigger: spin, announce, call the handler. */
+{
+    readonly type: 'trigger';
+}
+/** A refresh started without a pull; `callHandler` for the user's request. */
+ | {
+    readonly type: 'begin';
+    readonly callHandler: boolean;
+}
+/** The finger let go: settle onto the inset or back to the top. */
+ | {
+    readonly type: 'settle';
+    readonly to: 'inset' | 'top';
+}
+/** The refresh ended: remove the inset and hide the indicator. */
+ | {
+    readonly type: 'end';
+};
+export declare const INITIAL_REFRESH_STATE: RefreshState;
+export declare function reduceRefresh(state: RefreshState, event: RefreshEvent): {
+    state: RefreshState;
+    effects: ReadonlyArray<RefreshEffect>;
+};
+//# sourceMappingURL=refreshModel.d.ts.map

package/dist/RefreshControl/refreshModel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshModel.d.ts","sourceRoot":"","sources":["../../src/RefreshControl/refreshModel.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAeH,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,MAAM,YAAY,GACpB;IAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAC,GAC5B;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GACD;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAC,GAC1B;IAAC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAC,GAC7B;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAAC,GAC7D;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAC,CAAC;AAE3B,MAAM,MAAM,aAAa;AACvB,sEAAsE;AACpE;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAC;AAC5B,8EAA8E;GAC5E;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAAC;AACzD,mEAAmE;GACjE;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,KAAK,CAAA;CAAC;AACzD,kEAAkE;GAChE;IAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAC,CAAC;AAE3B,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAC;AAEF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,YAAY,EACnB,KAAK,EAAE,YAAY,GAClB;IAAC,KAAK,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CAAC,CAgD9D"}

package/dist/RefreshControl/refreshModel.js

@@ -0,0 +1,116 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file refreshModel.ts
+ * @input Pull events from the refresh pull recognizer, and programmatic begin
+ *   and end requests
+ * @output Exports reduceRefresh (UIRefreshControl's state machine as a pure
+ *   reducer that returns the effects to run), the initial state and types
+ * @position Pure logic for useRefreshControl; no DOM, no React
+ *
+ * SYNC: When modified, update:
+ * - /packages/lab/src/RefreshControl/refreshModel.test.ts
+ */
+
+// The rules, as UIKit runs them:
+// - A pull triggers once, with the finger down, when its overscroll reaches
+//   the trigger distance. Only overscroll that a finger drives triggers, never
+//   a momentum overshoot.
+// - A release settles onto the refreshing inset while refreshing, and back to
+//   the top otherwise. A cancelled pull settles the same way.
+// - A programmatic begin puts the control in the refreshing state. It calls
+//   the refresh handler only when it stands for the user's request, not when
+//   the app reports a refresh that it started.
+// - Ending a refresh that is not running does nothing.
+//
+// One refresh runs at a time: a pull while refreshing only stretches.
+
+export const INITIAL_REFRESH_STATE = {
+  isRefreshing: false,
+  isPulling: false,
+  hasTriggered: false
+};
+export function reduceRefresh(state, event) {
+  switch (event.type) {
+    case 'pullStart':
+      return {
+        state: {
+          ...state,
+          isPulling: true,
+          hasTriggered: false
+        },
+        effects: []
+      };
+    case 'pullMove':
+      {
+        // One refresh at a time: a pull while refreshing only stretches.
+        if (!state.isPulling || state.hasTriggered || state.isRefreshing || event.overscroll < event.trigger) {
+          return {
+            state,
+            effects: []
+          };
+        }
+        return {
+          state: {
+            ...state,
+            isRefreshing: true,
+            hasTriggered: true
+          },
+          effects: [{
+            type: 'trigger'
+          }]
+        };
+      }
+    case 'pullEnd':
+    case 'pullCancel':
+      if (!state.isPulling) {
+        return {
+          state,
+          effects: []
+        };
+      }
+      return {
+        state: {
+          ...state,
+          isPulling: false
+        },
+        effects: [{
+          type: 'settle',
+          to: state.isRefreshing ? 'inset' : 'top'
+        }]
+      };
+    case 'begin':
+      if (state.isRefreshing) {
+        return {
+          state,
+          effects: []
+        };
+      }
+      return {
+        state: {
+          ...state,
+          isRefreshing: true
+        },
+        effects: [{
+          type: 'begin',
+          callHandler: event.source === 'user'
+        }]
+      };
+    case 'end':
+      if (!state.isRefreshing) {
+        return {
+          state,
+          effects: []
+        };
+      }
+      return {
+        state: {
+          ...state,
+          isRefreshing: false
+        },
+        effects: [{
+          type: 'end'
+        }]
+      };
+  }
+}

package/dist/RefreshControl/refreshPull.d.ts

@@ -0,0 +1,69 @@
+/** The refreshing inset and one-to-one stretch, pt. */
+export declare const REFRESH_HEIGHT: number;
+/**
+ * Which mapping a pull follows.
+ * - `reveal`: before the trigger. One to one up to `height`, then the rubber
+ *   band on the excess.
+ * - `band`: after a trigger within twice the height, and for a pull from the
+ *   refreshing inset. One to one up to twice the height, then the rubber band.
+ */
+export type PullMode = 'reveal' | 'band';
+/**
+ * Overscroll shown for `travel` px of pull (the pan's translation, which
+ * already leaves out its hysteresis). `dimension` is the scroll owner's
+ * height, the rubber band's dimension.
+ */
+export declare function pullOverscroll(travel: number, dimension: number, mode: PullMode): number;
+/**
+ * How fast the overscroll moves per px of finger travel at `travel`: 1 where
+ * it tracks the finger, the rubber band's slope past it. A release's speed
+ * times this slope is the content's speed, which its settle starts at.
+ */
+export declare function pullSlope(travel: number, dimension: number, mode: PullMode): number;
+/**
+ * The travel that shows `overscroll`: where a finger landing on content
+ * already pulled (a re-grab mid-settle) resumes without a jump.
+ */
+export declare function pullTravel(overscroll: number, dimension: number, mode: PullMode): number;
+/**
+ * The mapping after a trigger at `travel`. It is the one-to-one band when the
+ * trigger falls within it, and the next frame steps onto the finger. Otherwise
+ * it is the reveal mapping, as when a tall scroll view triggers past the band.
+ */
+export declare function modeAfterTrigger(travel: number): PullMode;
+/**
+ * The overscroll at which a pull triggers, for a scroll owner `dimension`
+ * tall: a fraction of its height, never below the minimum.
+ */
+export declare function triggerDistance(dimension: number): number;
+/** How much of the indicator a pull reveals, 0 to 1 (linear in the pull). */
+export declare function revealFraction(overscroll: number, dimension: number): number;
+/** The reveal fraction on UIKit's reveal curve: the indicator's opacity. */
+export declare function revealProgress(overscroll: number, dimension: number): number;
+/**
+ * Where the content comes to rest when the finger lifts: on the refreshing
+ * inset while refreshing, back at the top otherwise.
+ */
+export declare function releaseTarget(isRefreshing: boolean): number;
+/**
+ * How the end of a refresh moves the content. `scrolled` (≥ 0) is how far the
+ * scroll owner is scrolled with the inset still in place. While the gap
+ * shows, the content slides up until the gap closes: the inset animates from
+ * `height` to `scrolled`. Then the inset and the scroll offset drop together
+ * with no visible change. Scrolled past the gap, nothing moves, and the inset
+ * and the offset drop at once.
+ */
+export declare function endMotion(scrolled: number): {
+    animateTo: number | null;
+    scrollBy: number;
+};
+/**
+ * The end's duration and curve: the theme tokens that `refreshControl` names,
+ * as the end's element computes them. Null when either token is missing or
+ * in a form it cannot read, such as `calc()`, `var()` or `steps()`.
+ */
+export declare function endTiming(style: Pick<CSSStyleDeclaration, 'getPropertyValue'>): {
+    ms: number;
+    points: readonly [number, number, number, number];
+} | null;
+//# sourceMappingURL=refreshPull.d.ts.map

package/dist/RefreshControl/refreshPull.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshPull.d.ts","sourceRoot":"","sources":["../../src/RefreshControl/refreshPull.ts"],"names":[],"mappings":"AAmCA,uDAAuD;AACvD,eAAO,MAAM,cAAc,EAAE,MAA8B,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAQzC;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GACb,MAAM,CASR;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GACb,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GACb,MAAM,CASR;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAEzD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAKzD;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5E;AAID,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,OAAO,GAAG,MAAM,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG;IAC3C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAOA;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,GACnD;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CAAC,GAAG,IAAI,CASxE"}

package/dist/RefreshControl/refreshPull.js

@@ -0,0 +1,159 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file refreshPull.ts
+ * @input The pull values (refreshValues.ts), and the rubber band, the cubic
+ *   Bézier and the motion-role parsers (Core's internal touch entry)
+ * @output Exports the pull mapping (finger travel → overscroll), its slope
+ *   and its inverse, and the trigger distance. It also exports the reveal, a
+ *   refresh's release and end targets, and the end's timing from the theme's
+ *   tokens.
+ * @position Pure math for useRefreshControl; no DOM, no React
+ *
+ * SYNC: When modified, update:
+ * - /packages/lab/src/RefreshControl/refreshPull.test.ts
+ */
+
+// UIKit's refresh pull, as measured: the first `height` of overscroll tracks
+// the finger one to one, after the pan's hysteresis. Past it, the scroll
+// view's rubber band applies to the excess. The trigger distance grows with
+// the scroll view's height. After a trigger within twice the height, the
+// overscroll steps back onto the finger. It stays one to one up to twice the
+// height, with resistance past that.
+
+import { cubicBezier } from '@astryxdesign/core/internal/touch';
+import { rubberBand, rubberBandInverse, rubberBandSlope } from '@astryxdesign/core/internal/touch';
+import { parseCssEasing, parseMotionRoleValue } from '@astryxdesign/core/internal/touch';
+import { refreshControl } from "./refreshValues.js";
+
+/** The refreshing inset and one-to-one stretch, pt. */
+export const REFRESH_HEIGHT = refreshControl.height;
+
+/**
+ * Which mapping a pull follows.
+ * - `reveal`: before the trigger. One to one up to `height`, then the rubber
+ *   band on the excess.
+ * - `band`: after a trigger within twice the height, and for a pull from the
+ *   refreshing inset. One to one up to twice the height, then the rubber band.
+ */
+
+function linearStretch(mode) {
+  return mode === 'band' ? refreshControl.height * refreshControl.postTriggerLinearHeights : refreshControl.height;
+}
+
+/**
+ * Overscroll shown for `travel` px of pull (the pan's translation, which
+ * already leaves out its hysteresis). `dimension` is the scroll owner's
+ * height, the rubber band's dimension.
+ */
+export function pullOverscroll(travel, dimension, mode) {
+  if (!(travel > 0)) {
+    return 0;
+  }
+  const linear = linearStretch(mode);
+  if (travel <= linear) {
+    return travel;
+  }
+  return linear + rubberBand(travel - linear, dimension);
+}
+
+/**
+ * How fast the overscroll moves per px of finger travel at `travel`: 1 where
+ * it tracks the finger, the rubber band's slope past it. A release's speed
+ * times this slope is the content's speed, which its settle starts at.
+ */
+export function pullSlope(travel, dimension, mode) {
+  if (!(travel > 0)) {
+    return 0;
+  }
+  const linear = linearStretch(mode);
+  return travel <= linear ? 1 : rubberBandSlope(travel - linear, dimension);
+}
+
+/**
+ * The travel that shows `overscroll`: where a finger landing on content
+ * already pulled (a re-grab mid-settle) resumes without a jump.
+ */
+export function pullTravel(overscroll, dimension, mode) {
+  if (!(overscroll > 0)) {
+    return 0;
+  }
+  const linear = linearStretch(mode);
+  if (overscroll <= linear) {
+    return overscroll;
+  }
+  return linear + rubberBandInverse(overscroll - linear, dimension);
+}
+
+/**
+ * The mapping after a trigger at `travel`. It is the one-to-one band when the
+ * trigger falls within it, and the next frame steps onto the finger. Otherwise
+ * it is the reveal mapping, as when a tall scroll view triggers past the band.
+ */
+export function modeAfterTrigger(travel) {
+  return travel <= linearStretch('band') ? 'band' : 'reveal';
+}
+
+/**
+ * The overscroll at which a pull triggers, for a scroll owner `dimension`
+ * tall: a fraction of its height, never below the minimum.
+ */
+export function triggerDistance(dimension) {
+  return Math.max(refreshControl.triggerMinimum, refreshControl.triggerHeightFraction * Math.max(0, dimension));
+}
+
+/** How much of the indicator a pull reveals, 0 to 1 (linear in the pull). */
+export function revealFraction(overscroll, dimension) {
+  return Math.min(1, Math.max(0, overscroll / triggerDistance(dimension)));
+}
+const revealEasing = cubicBezier(refreshControl.revealCurve);
+
+/** The reveal fraction on UIKit's reveal curve: the indicator's opacity. */
+export function revealProgress(overscroll, dimension) {
+  return revealEasing(revealFraction(overscroll, dimension));
+}
+
+/**
+ * Where the content comes to rest when the finger lifts: on the refreshing
+ * inset while refreshing, back at the top otherwise.
+ */
+export function releaseTarget(isRefreshing) {
+  return isRefreshing ? refreshControl.height : 0;
+}
+
+/**
+ * How the end of a refresh moves the content. `scrolled` (≥ 0) is how far the
+ * scroll owner is scrolled with the inset still in place. While the gap
+ * shows, the content slides up until the gap closes: the inset animates from
+ * `height` to `scrolled`. Then the inset and the scroll offset drop together
+ * with no visible change. Scrolled past the gap, nothing moves, and the inset
+ * and the offset drop at once.
+ */
+export function endMotion(scrolled) {
+  const height = refreshControl.height;
+  const offset = Math.max(0, scrolled);
+  if (offset >= height) {
+    return {
+      animateTo: null,
+      scrollBy: -height
+    };
+  }
+  return {
+    animateTo: offset,
+    scrollBy: -offset
+  };
+}
+
+/**
+ * The end's duration and curve: the theme tokens that `refreshControl` names,
+ * as the end's element computes them. Null when either token is missing or
+ * in a form it cannot read, such as `calc()`, `var()` or `steps()`.
+ */
+export function endTiming(style) {
+  const ms = parseMotionRoleValue('duration', style.getPropertyValue(refreshControl.endDurationToken));
+  const points = parseCssEasing(style.getPropertyValue(refreshControl.endEasingToken));
+  return ms == null || points == null ? null : {
+    ms,
+    points
+  };
+}

package/dist/RefreshControl/refreshTouchController.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file refreshTouchController.ts
+ * @input The refresh's state and dispatch (refreshModel.ts), the pull's
+ *   mapping (refreshPull.ts), and Core's internal touch entry
+ * @output useRefreshTouchController: the refresh's touch layer (the pull, the
+ *   inset, the indicator's place and every motion) and its refs
+ * @position Internal to useRefreshControl; useRefreshControl.ts is its one
+ *   import site, so a page loads this code only with the hook.
+ *
+ * SYNC: When modified, update:
+ * - /packages/lab/src/RefreshControl/useRefreshControl.ts
+ * - /packages/lab/src/RefreshControl/useRefreshControl.test.tsx
+ */
+import { type RefCallback } from 'react';
+import type { RefreshEvent, RefreshState } from './refreshModel.js';
+export interface RefreshTouchControllerOptions {
+    /** Whether the pull applies. */
+    readonly isPullEnabled: boolean;
+    /** The state machine's state, shared with the wiring. */
+    readonly model: {
+        readonly current: RefreshState;
+    };
+    /** The wiring's dispatch: the pull's events go to the state machine. */
+    readonly dispatchRef: {
+        readonly current: (event: RefreshEvent) => void;
+    };
+}
+export interface RefreshTouchController {
+    readonly contentRef: RefCallback<HTMLElement>;
+    readonly indicatorRef: RefCallback<HTMLElement>;
+    /** A pull triggered: the indicator shows in full; the release settles onto the inset. */
+    trigger(): void;
+    /** A refresh began without a pull: the inset arrives with no visible motion. */
+    begin(): void;
+    /** The release settles onto the inset or back to the top. */
+    settle(to: 'inset' | 'top'): void;
+    /** The refresh ended. */
+    end(): void;
+}
+/**
+ * The refresh's touch layer. The wiring owns the state and the
+ * announcements; this owns everything a finger drives.
+ */
+export declare function useRefreshTouchController({ isPullEnabled, model, dispatchRef, }: RefreshTouchControllerOptions): RefreshTouchController;
+//# sourceMappingURL=refreshTouchController.d.ts.map

package/dist/RefreshControl/refreshTouchController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refreshTouchController.d.ts","sourceRoot":"","sources":["../../src/RefreshControl/refreshTouchController.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AA0BH,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,OAAO,CAAC;AAcf,OAAO,KAAK,EAAC,YAAY,EAAE,YAAY,EAAC,MAAM,gBAAgB,CAAC;AAe/D,MAAM,WAAW,6BAA6B;IAC5C,gCAAgC;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE;QAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;KAAC,CAAC;IACjD,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE;QAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;KAAC,CAAC;CACzE;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAChD,yFAAyF;IACzF,OAAO,IAAI,IAAI,CAAC;IAChB,gFAAgF;IAChF,KAAK,IAAI,IAAI,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAAC;IAClC,yBAAyB;IACzB,GAAG,IAAI,IAAI,CAAC;CACb;AA6ED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,aAAa,EACb,KAAK,EACL,WAAW,GACZ,EAAE,6BAA6B,GAAG,sBAAsB,CA8oBxD"}