@astryxdesign/lab 0.7.9-canary.2ea8f68 → 0.7.9-canary.2f035fe

package/blocks/CommentThreadShowcase.tsx

@@ -36,7 +36,7 @@ export default function CommentThreadShowcase() {
   });
 
   return (
-    <Card padding={0} width={340}>
+    <Card padding={0} width="100%" maxWidth={340}>
       <CommentThread
         comment={thread}
         currentUser={VIEWER}

package/dist/Chart/formatters.d.ts

@@ -1,10 +1,11 @@
 /**
  * @file formatters.ts
- * @input Tick values and optional BCP 47 locale tags
+ * @input Tick values, optional BCP 47 locale tags, and for dates an optional
+ *   calendar
  * @output Built-in tick format utilities for common data types
  * @position Utility; consumed by ChartAxis via tickFormat prop
  */
-import type { Locale } from '@astryxdesign/core/i18n';
+import type { CalendarSystem, Locale } from '@astryxdesign/core/i18n';
 /**
  * Compact number formatter (e.g. 1200 → "1.2K", 1500000 → "1.5M")
  */
@@ -25,11 +26,13 @@ export declare function currency(symbol?: string, locale?: Locale): (value: unkn
  */
 export declare function percent(value: unknown): string;
 /**
- * Date formatter — short date (e.g. "Jan 5", "Mar 12")
+ * Date formatter — short date (e.g. "Jan 5", "Mar 12"), in `calendar`
+ * (Gregorian by default)
  */
-export declare function shortDate(value: unknown, locale?: Locale): string;
+export declare function shortDate(value: unknown, locale?: Locale, calendar?: CalendarSystem): string;
 /**
- * Date formatter — month/year (e.g. "Jan 2024", "Mar 2025")
+ * Date formatter — month/year (e.g. "Jan 2024", "Mar 2025"), in `calendar`
+ * (Gregorian by default)
  */
-export declare function monthYear(value: unknown, locale?: Locale): string;
+export declare function monthYear(value: unknown, locale?: Locale, calendar?: CalendarSystem): string;
 //# sourceMappingURL=formatters.d.ts.map

package/dist/Chart/formatters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/Chart/formatters.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAepD;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,MAAM,SAAM,EACZ,MAAM,GAAE,MAAa,GACpB,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAiB5B;AAQD;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAM9C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,GAAE,MAAa,GAAG,MAAM,CAUvE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,GAAE,MAAa,GAAG,MAAM,CAUvE"}
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../../src/Chart/formatters.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAE,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpE;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAepD;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,MAAM,SAAM,EACZ,MAAM,GAAE,MAAa,GACpB,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAiB5B;AAQD;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAM9C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,MAAM,GAAE,MAAa,EACrB,QAAQ,GAAE,cAA0B,GACnC,MAAM,CAUR;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,MAAM,GAAE,MAAa,EACrB,QAAQ,GAAE,cAA0B,GACnC,MAAM,CAUR"}

package/dist/Chart/formatters.js

@@ -2,11 +2,14 @@
 
 /**
  * @file formatters.ts
- * @input Tick values and optional BCP 47 locale tags
+ * @input Tick values, optional BCP 47 locale tags, and for dates an optional
+ *   calendar
  * @output Built-in tick format utilities for common data types
  * @position Utility; consumed by ChartAxis via tickFormat prop
  */
 
+import { plainDateFormat, plainDateFromDate } from '@astryxdesign/core/utils';
+
 /**
  * Compact number formatter (e.g. 1200 → "1.2K", 1500000 → "1.5M")
  */
@@ -74,31 +77,33 @@ export function percent(value) {
 }
 
 /**
- * Date formatter — short date (e.g. "Jan 5", "Mar 12")
+ * Date formatter — short date (e.g. "Jan 5", "Mar 12"), in `calendar`
+ * (Gregorian by default)
  */
-export function shortDate(value, locale = 'en') {
+export function shortDate(value, locale = 'en', calendar = 'gregory') {
   const d = value instanceof Date ? value : new Date(Number(value));
   if (isNaN(d.getTime())) {
     return String(value);
   }
-  return new Intl.DateTimeFormat(locale, {
+  return plainDateFormat(plainDateFromDate(d), {
     month: 'short',
     day: 'numeric',
-    calendar: 'gregory'
-  }).format(d);
+    calendar
+  }, locale);
 }
 
 /**
- * Date formatter — month/year (e.g. "Jan 2024", "Mar 2025")
+ * Date formatter — month/year (e.g. "Jan 2024", "Mar 2025"), in `calendar`
+ * (Gregorian by default)
  */
-export function monthYear(value, locale = 'en') {
+export function monthYear(value, locale = 'en', calendar = 'gregory') {
   const d = value instanceof Date ? value : new Date(Number(value));
   if (isNaN(d.getTime())) {
     return String(value);
   }
-  return new Intl.DateTimeFormat(locale, {
+  return plainDateFormat(plainDateFromDate(d), {
     month: 'short',
     year: 'numeric',
-    calendar: 'gregory'
-  }).format(d);
+    calendar
+  }, locale);
 }

package/dist/CircularProgress/CircularProgress.d.ts

@@ -1,7 +1,8 @@
 /**
  * @file CircularProgress.tsx
  * @input Uses React (useId, refs, layout effects), stylex, SVG, Web
- *   Animations, color/spacing/duration/ease tokens
+ *   Animations, color/spacing/duration/ease tokens, and Spinner's rotor
+ *   (core internal/spinner-rotor) for the indeterminate ring
  * @output Exports CircularProgress component, CircularProgressProps, CircularProgressSize, CircularProgressVariant types
  * @position Core implementation; consumed by index.ts
  *
@@ -89,7 +90,8 @@ export interface CircularProgressProps extends BaseProps<HTMLDivElement> {
      */
     variant?: CircularProgressVariant;
     /**
-     * When true, renders an animated indeterminate progress indicator.
+     * When true, renders an animated indeterminate progress indicator: an arc
+     * that turns as Spinner's does.
      * Use when the progress amount is unknown (e.g. loading, processing).
      * The `value` and `hasValueLabel` props are ignored in this mode.
      * Respects `prefers-reduced-motion` by slowing the animation.

package/dist/CircularProgress/CircularProgress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CircularProgress.d.ts","sourceRoot":"","sources":["../../src/CircularProgress/CircularProgress.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAYrE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAGlD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,IAAI,CAAC;CACf;AAED,MAAM,MAAM,uBAAuB,GAAG,MAAM,0BAA0B,CAAC;AAEvE,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAWtD,MAAM,WAAW,qBAAsB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACtE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAClC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAmWD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,KAAS,EACT,GAAS,EACT,KAAK,EACL,aAAoB,EACpB,aAAqB,EACrB,gBAA0C,EAC1C,QAAQ,EACR,IAAW,EACX,OAAkB,EAClB,eAAuB,EACvB,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,UAAU,EACzB,GAAG,EACH,GAAG,IAAI,EACR,EAAE,qBAAqB,+BA+QvB;yBAjSe,gBAAgB"}
+{"version":3,"file":"CircularProgress.d.ts","sourceRoot":"","sources":["../../src/CircularProgress/CircularProgress.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAiBrE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAGlD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,IAAI,CAAC;IACb,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,IAAI,CAAC;CACf;AAED,MAAM,MAAM,uBAAuB,GAAG,MAAM,0BAA0B,CAAC;AAEvE,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAWtD,MAAM,WAAW,qBAAsB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACtE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAClC;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA2TD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,KAAS,EACT,GAAS,EACT,KAAK,EACL,aAAoB,EACpB,aAAqB,EACrB,gBAA0C,EAC1C,QAAQ,EACR,IAAW,EACX,OAAkB,EAClB,eAAuB,EACvB,UAAkB,EAClB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,UAAU,EACzB,GAAG,EACH,GAAG,IAAI,EACR,EAAE,qBAAqB,+BAqRvB;yBAvSe,gBAAgB"}

package/dist/CircularProgress/CircularProgress.js

@@ -5,7 +5,8 @@
 /**
  * @file CircularProgress.tsx
  * @input Uses React (useId, refs, layout effects), stylex, SVG, Web
- *   Animations, color/spacing/duration/ease tokens
+ *   Animations, color/spacing/duration/ease tokens, and Spinner's rotor
+ *   (core internal/spinner-rotor) for the indeterminate ring
  * @output Exports CircularProgress component, CircularProgressProps, CircularProgressSize, CircularProgressVariant types
  * @position Core implementation; consumed by index.ts
  *
@@ -19,6 +20,7 @@ import { useId, useLayoutEffect, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import '@astryxdesign/core/theme/tokens.stylex';
 import { colorVars, durationVars, easeVars, fontWeightVars, spacingVars, typeScaleVars } from '@astryxdesign/core/theme/tokens.stylex';
+import { SPINNER_ARC_FRACTION, spinnerRotorStyles, syncRotationPhase } from '@astryxdesign/core/internal/spinner-rotor';
 import { mergeProps } from '@astryxdesign/core/utils';
 import { themeProps } from '@astryxdesign/core/utils';
 
@@ -52,16 +54,6 @@ const SIZE_CONFIG = {
     strokeWidth: 5
   }
 };
-// =============================================================================
-// Indeterminate animation
-// =============================================================================
-
-const indeterminateRotation = "xqng64z-B";
-
-// SVG dash percentages scale with the square viewport. A 300% gap exceeds every
-// ring circumference; shifting the 2% + 300% pattern by 302% closes the loop.
-const indeterminateDash = "x9ppb3p-B";
-
 // =============================================================================
 // Styles
 // =============================================================================
@@ -80,6 +72,15 @@ const styles = {
     kOIVth: "xzye2dw",
     $$css: true
   },
+  svg: {
+    k1xSpc: "x1lliihq",
+    k3aq6I: "x9tu13d",
+    $$css: true
+  },
+  svgIndeterminate: {
+    k1xSpc: "x1lliihq",
+    $$css: true
+  },
   track: {
     kDwRjp: "xbh8q5q",
     kjVXCG: "xpi25hw",
@@ -98,10 +99,6 @@ const styles = {
   fillIndeterminate: {
     kDwRjp: "xbh8q5q",
     kU5bRw: "x1owpc8m",
-    kKVMdj: "x16zax3f",
-    k44tkh: "xmg6eyc xnh0sag",
-    kyAemX: "x4hg4is",
-    ko0y90: "xa4qsjk",
     $$css: true
   }
 };
@@ -462,14 +459,8 @@ export function CircularProgress({
         width: diameter,
         height: diameter,
         viewBox: `0 0 ${diameter} ${diameter}`,
-        ...{
-          0: {
-            className: "x1lliihq x9tu13d"
-          },
-          1: {
-            className: "x1lliihq x1ka1v4i x1c74tu6 xy02sl2 x1esw782 xa4qsjk"
-          }
-        }[!!isIndeterminate << 0],
+        ref: isIndeterminate ? syncRotationPhase : undefined,
+        ...stylex.props(isIndeterminate ? styles.svgIndeterminate : styles.svg, isIndeterminate && spinnerRotorStyles.turn),
         children: [/*#__PURE__*/_jsx("circle", {
           ...mergeProps(themeProps('circular-progress-track'), stylex.props(styles.track, trackVariantStyles[trackVariant])),
           cx: center,
@@ -484,6 +475,11 @@ export function CircularProgress({
           cy: center,
           r: radius,
           strokeWidth: strokeWidth
+          // Spinner's arc: the same fraction of the ring, starting at 12
+          // o'clock.
+          ,
+          strokeDasharray: `${circumference * SPINNER_ARC_FRACTION} ${circumference * (1 - SPINNER_ARC_FRACTION)}`,
+          transform: `rotate(-90 ${center} ${center})`
         }) : null]
       }), isIndeterminate ? null :
       /*#__PURE__*/

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'
+        }]
+      };
+  }
+}