@sigx/lynx-gestures 0.4.0 → 0.4.2

package/src/components/Pressable.tsx

@@ -16,6 +16,17 @@ export type PressableProps =
   & Define.Prop<'disabled', boolean, false>
   & Define.Prop<'class', string, false>
   & Define.Prop<'style', Record<string, string | number>, false>
+  // Accessibility passthrough — forwarded onto the inner <view> so the
+  // interactive node (the one that owns the tap handler) is also the one
+  // screen readers activate. Without these, callers who want a11y on a
+  // Pressable have to wrap it in an outer accessibility-element <view>,
+  // which puts the metadata and the gesture handler on different nodes
+  // and breaks screen-reader activation.
+  & Define.Prop<'accessibility-element', boolean, false>
+  & Define.Prop<'accessibility-label', string, false>
+  & Define.Prop<'accessibility-role', string, false>
+  & Define.Prop<'accessibility-trait', string, false>
+  & Define.Prop<'accessibility-status', string, false>
   & Define.Slot<'default'>
   & Define.Event<'press', void>
   & Define.Event<'longPress', void>;
@@ -57,9 +68,10 @@ interface PressableMTState {
  * `LongPress.onEnd` skips press emission when the touch drifted past
  * the threshold (matching Tap's success criteria).
  *
- * Disabled is captured at setup; runtime toggling won't update an active
- * gesture's behavior. Wrap the parent in conditional rendering for now if
- * dynamic disable is needed.
+ * `disabled` reads live from a `MainThreadRef` so flipping it after mount
+ * (e.g. a `<Button loading>` toggling on) immediately suppresses both
+ * visual feedback and emit, without remounting the component or the
+ * underlying gesture registration.
  */
 export const Pressable = component<PressableProps>(({ props, slots, emit }) => {
   const elRef = useMainThreadRef<MainThread.Element | null>(null);
@@ -74,7 +86,11 @@ export const Pressable = component<PressableProps>(({ props, slots, emit }) => {
   const minDuration = longPressDuration > 0 ? longPressDuration : 1_000_000;
   const maxDistance = props.maxDistance ?? 10;
   const maxDistanceSq = maxDistance * maxDistance;
-  const disabled = props.disabled ?? false;
+
+  // Reactive `disabled` — worklets read `disabledRef.current` so prop
+  // changes after mount take effect without re-registering the gesture.
+  // The render fn below keeps this ref in sync each pass.
+  const disabledRef = useMainThreadRef<boolean>(!!props.disabled);
 
   const state = useMainThreadRef<PressableMTState>({
     longPressFired: false,
@@ -87,7 +103,7 @@ export const Pressable = component<PressableProps>(({ props, slots, emit }) => {
     .maxDistance(maxDistance)
     .onBegin((e: any) => {
       'main thread';
-      if (disabled) return;
+      if (disabledRef.current) return;
       // Reset the cross-platform state on every fresh touch-down. Both
       // Tap.onBegin and LongPress.onBegin fire — first one wins, second
       // is a no-op because pressEmitted/longPressFired are already false.
@@ -103,7 +119,7 @@ export const Pressable = component<PressableProps>(({ props, slots, emit }) => {
     })
     .onStart(() => {
       'main thread';
-      if (disabled) return;
+      if (disabledRef.current) return;
       // Android path: Tap.onStart fires on touchend within maxDuration;
       // emit press here. The LongPress.onEnd fallback below is gated on
       // !pressEmitted so it won't double-fire on Android.
@@ -129,7 +145,7 @@ export const Pressable = component<PressableProps>(({ props, slots, emit }) => {
     .maxDistance(maxDistance)
     .onBegin(() => {
       'main thread';
-      if (disabled) return;
+      if (disabledRef.current) return;
       // Idempotent with Tap.onBegin — both fire on touch-down. State has
       // already been initialised by Tap.onBegin (whichever fires first).
       elRef.current?.setStyleProperties({
@@ -139,7 +155,7 @@ export const Pressable = component<PressableProps>(({ props, slots, emit }) => {
     })
     .onStart(() => {
       'main thread';
-      if (disabled) return;
+      if (disabledRef.current) return;
       state.current.longPressFired = true;
       runOnBackground(() => { emit('longPress'); })();
     })
@@ -151,7 +167,7 @@ export const Pressable = component<PressableProps>(({ props, slots, emit }) => {
         opacity: 1,
         transform: 'scale(1)',
       });
-      if (disabled) return;
+      if (disabledRef.current) return;
       // iOS fallback path. On iOS Tap.onStart never fires, so press would
       // never emit without this. On Android this is a no-op because
       // pressEmitted is already true (or longPressFired is true).
@@ -169,13 +185,23 @@ export const Pressable = component<PressableProps>(({ props, slots, emit }) => {
 
   useGestureDetector(elRef, gesture);
 
-  return () => (
-    <view
-      class={props.class}
-      style={props.style}
-      main-thread:ref={elRef}
-    >
-      {slots.default?.()}
-    </view>
-  );
+  return () => {
+    // Keep the reactive-disabled ref in sync with the prop on every render.
+    // Worklets read `.current` at call time, so this is the only writer.
+    disabledRef.current = !!props.disabled;
+    return (
+      <view
+        class={props.class}
+        style={props.style}
+        main-thread:ref={elRef}
+        accessibility-element={props['accessibility-element']}
+        accessibility-label={props['accessibility-label']}
+        accessibility-role={props['accessibility-role']}
+        accessibility-trait={props['accessibility-trait']}
+        accessibility-status={props['accessibility-status']}
+      >
+        {slots.default?.()}
+      </view>
+    );
+  };
 });

package/src/components/ScrollView.tsx

@@ -8,7 +8,7 @@ import {
   type Define,
   type MainThread,
 } from '@sigx/lynx';
-import { useScrollContext } from '../scroll-context';
+import { useScrollContext } from '../scroll-context.js';
 
 export type ScrollViewProps =
   & Define.Prop<'offsetX', SharedValue<number>, false>

package/src/components/Swipeable.tsx

@@ -9,7 +9,7 @@ import {
   type Define,
   type MainThread,
 } from '@sigx/lynx';
-import { useScrollContext } from '../scroll-context';
+import { useScrollContext } from '../scroll-context.js';
 
 export type SwipeSide = 'left' | 'right';
 

package/src/components/Swiper.tsx

@@ -0,0 +1,204 @@
+import {
+  component,
+  effect,
+  runOnMainThread,
+  signal,
+  useElementLayout,
+  useMainThreadRef,
+  useSharedValue,
+  type SharedValue,
+  type Define,
+  type MainThread,
+} from '@sigx/lynx';
+import type { PrimitiveSignal } from '@sigx/reactivity';
+
+// Read the logical screen width once at module load — used as the page
+// width fallback before the Swiper's own layout box has been measured.
+// Matches the same `lynx.SystemInfo` reads used by lynx-navigation, so
+// fullscreen / edge-to-edge layouts line up.
+declare const lynx:
+  | { SystemInfo?: { pixelWidth?: number; pixelHeight?: number; pixelRatio?: number } }
+  | undefined;
+
+const SCREEN_WIDTH_FALLBACK = (() => {
+  try {
+    const info = typeof lynx !== 'undefined' ? lynx?.SystemInfo : undefined;
+    const px = info?.pixelWidth;
+    const pr = info?.pixelRatio || 1;
+    if (typeof px === 'number' && px > 0) return Math.round(px / pr);
+  } catch {
+    /* ignore */
+  }
+  return 400;
+})();
+
+const SCREEN_HEIGHT_FALLBACK = (() => {
+  try {
+    const info = typeof lynx !== 'undefined' ? lynx?.SystemInfo : undefined;
+    const px = info?.pixelHeight;
+    const pr = info?.pixelRatio || 1;
+    if (typeof px === 'number' && px > 0) return Math.round(px / pr);
+  } catch {
+    /* ignore */
+  }
+  return 800;
+})();
+
+export type SwiperProps<T = unknown> =
+  /**
+   * The items to render — one page per item. Switched from slot-based
+   * children because horizontal `<scroll-view>` children need explicit
+   * pixel widths (Lynx doesn't resolve `width: 100%` against the viewport
+   * in a horizontal scroller), so the Swiper has to own the page wrapper.
+   */
+  & Define.Prop<'items', readonly T[], true>
+  /** Per-item renderer. Output is wrapped in a page-width sized `<view>`. */
+  & Define.Prop<'renderItem', (item: T, index: number) => unknown, true>
+  /** Optional key extractor — defaults to the item's array index. */
+  & Define.Prop<'keyExtractor', (item: T, index: number) => string | number, false>
+  /**
+   * Page width in CSS pixels. Defaults to the Swiper's own measured
+   * container width via `useElementLayout`, falling back to
+   * `lynx.SystemInfo.pixelWidth / pixelRatio` before the first layout
+   * pass.
+   */
+  & Define.Prop<'width', number, false>
+  /** Page height in CSS pixels — applied to each page wrapper. */
+  & Define.Prop<'height', number | string, false>
+  /**
+   * Externally-observable current page (whole units). Updated from
+   * `bindscroll` as the user pans. Writes from outside (e.g.
+   * `idx.value = 2`) glide the swiper to that page via the native
+   * `<scroll-view>.scrollTo` UI method.
+   */
+  & Define.Prop<'index', PrimitiveSignal<number>, false>
+  /** Page to render first (uncontrolled-initial). */
+  & Define.Prop<'initialIndex', number, false>
+  /**
+   * MT-thread live pixel offset, updated every scroll frame from the
+   * native scroll-view's `scrollLeft`.
+   */
+  & Define.Prop<'offset', SharedValue<number>, false>
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>
+  /** Emitted (BG) when the page-rounded `scrollLeft / width` changes. */
+  & Define.Event<'pageChange', { index: number }>;
+
+/**
+ * Paged horizontal carousel built on Lynx's native `<scroll-view
+ * paging-enabled>` — native snap, no MTS pan handling required for the
+ * happy path. Items are rendered into page-sized `<view>` wrappers (the
+ * Swiper owns the sizing so Lynx's horizontal scroller has explicit
+ * widths to lay out against; `width: 100%` does NOT resolve to the
+ * viewport for `<scroll-view scroll-orientation="horizontal">` children).
+ *
+ * @example
+ * ```tsx
+ * const idx = signal(0);
+ * const offset = useSharedValue(0);
+ * <Swiper
+ *   items={photos}
+ *   index={idx}
+ *   offset={offset}
+ *   renderItem={(src) => (
+ *     <image src={src} mode="aspectFit" style={{ width: '100%', height: '100%' }} />
+ *   )}
+ * />
+ * ```
+ */
+export const Swiper = component<SwiperProps>(({ props, emit }) => {
+  const ownOffset = useSharedValue(0);
+  const ownIndex = signal(props.initialIndex ?? 0);
+
+  const { layout, onLayoutChange } = useElementLayout();
+  const scrollRef = useMainThreadRef<MainThread.Element | null>(null);
+
+  // Resolve the controlled-vs-uncontrolled signal/offset once at setup so the
+  // BG→MT reactive bridge below and the render closure share the same instance.
+  const offset = props.offset ?? ownOffset;
+  const idx = props.index ?? ownIndex;
+
+  // BG→MT bridge: when external code (or a dot tap) writes `idx.value = N`,
+  // we invoke the native `<scroll-view>.scrollTo` UI method on MT so the
+  // animation runs with platform physics (the same easing the user gets when
+  // they fling-snap). The dedup runs MT-side against the live scroll offset
+  // so we don't re-invoke for writes that just mirror a finished snap.
+  const scrollOnMT = runOnMainThread((index: number, pageW: number) => {
+    'main thread';
+    const el = scrollRef.current;
+    if (!el || pageW <= 0) return;
+    const target = index * pageW;
+    const current = offset.current.value;
+    if (Math.abs(current - target) < 0.5) return;
+    el.invoke('scrollTo', { index, smooth: true });
+  });
+
+  effect(() => {
+    const v = idx.value;
+    if (typeof v !== 'number') return;
+    const pw = props.width
+      ?? (layout.value && layout.value.width > 0 ? layout.value.width : undefined)
+      ?? SCREEN_WIDTH_FALLBACK;
+    scrollOnMT(v, pw);
+  });
+
+  return () => {
+    const pageWidth = props.width
+      ?? (layout.value && layout.value.width > 0 ? layout.value.width : undefined)
+      ?? SCREEN_WIDTH_FALLBACK;
+    // Lynx horizontal `<scroll-view>` doesn't resolve `height: 100%` on
+    // children (same constraint as width), so the page wrapper needs a
+    // pixel value. Use the measured layout height when available; the
+    // screen-height fallback covers the first paint. Guard against the
+    // `0 ?? fallback` gotcha — a zero-sized layout report (e.g. before
+    // first paint) must fall through to the fallback.
+    const measuredHeight = layout.value && layout.value.height > 0 ? layout.value.height : undefined;
+    const pageHeight: number | string = props.height
+      ?? measuredHeight
+      ?? SCREEN_HEIGHT_FALLBACK;
+    const initialScrollLeft = (props.initialIndex ?? 0) * pageWidth;
+    const items = props.items;
+    const keyOf = props.keyExtractor;
+    return (
+      <scroll-view
+        main-thread:ref={scrollRef}
+        scroll-orientation="horizontal"
+        paging-enabled
+        show-scrollbar={false}
+        bounces={true}
+        scroll-left={initialScrollLeft}
+        class={props.class}
+        style={{ width: '100%', ...(props.style || {}) }}
+        bindlayoutchange={onLayoutChange}
+        main-thread-bindscroll={(e: { detail: { scrollLeft: number } }) => {
+          'main thread';
+          offset.current.value = e.detail.scrollLeft;
+          const __flush = (globalThis as Record<string, unknown>)['__FlushElementTree'] as (() => void) | undefined;
+          if (__flush) __flush();
+        }}
+        bindscroll={(e: { detail: { scrollLeft: number } }) => {
+          if (pageWidth <= 0) return;
+          const next = Math.round(e.detail.scrollLeft / pageWidth);
+          if (next !== idx.value) {
+            idx.value = next;
+            emit('pageChange', { index: next });
+          }
+        }}
+      >
+        {items.map((item, i) => (
+          <view
+            key={keyOf ? String(keyOf(item, i)) : String(i)}
+            style={{
+              width: pageWidth + 'px',
+              height: typeof pageHeight === 'number' ? pageHeight + 'px' : pageHeight,
+              flexShrink: 0,
+              flexGrow: 0,
+            }}
+          >
+            {props.renderItem(item, i)}
+          </view>
+        ))}
+      </scroll-view>
+    );
+  };
+}) as <T>(props: SwiperProps<T>) => unknown;

package/src/index.ts

@@ -5,8 +5,8 @@
 // changes. The other legacy hooks (`useTap`, `useLongPress`, `usePan`,
 // `useFling`, `useSwipe`, `useGesture`, `usePanResponder`) were deleted in
 // Phase 2.12.4 — use `Gesture.*` + `useGestureDetector` instead.
-export { usePinch } from './use-pinch';
-export { useRotation } from './use-rotation';
+export { usePinch } from './use-pinch.js';
+export { useRotation } from './use-rotation.js';
 
 // Cross-thread value primitive — re-exported from @sigx/lynx for back-compat.
 // @deprecated since 0.3.0 — import directly from '@sigx/lynx' instead.
@@ -31,20 +31,34 @@ export type {
 } from '@sigx/lynx';
 
 // Built-in MT components (arena-driven via `Gesture.*` + `useGestureDetector`).
-export { Pressable } from './components/Pressable';
-export type { PressableProps } from './components/Pressable';
-export { Draggable } from './components/Draggable';
-export type { DraggableProps, DragEndDetail } from './components/Draggable';
-export { Swipeable } from './components/Swipeable';
-export type { SwipeableProps, SwipeSide } from './components/Swipeable';
-export { ScrollView } from './components/ScrollView';
-export type { ScrollViewProps } from './components/ScrollView';
+export { Pressable } from './components/Pressable.js';
+export type { PressableProps } from './components/Pressable.js';
+export { Draggable } from './components/Draggable.js';
+export type { DraggableProps, DragEndDetail } from './components/Draggable.js';
+export { Swipeable } from './components/Swipeable.js';
+export type { SwipeableProps, SwipeSide } from './components/Swipeable.js';
+export { ScrollView } from './components/ScrollView.js';
+export type { ScrollViewProps } from './components/ScrollView.js';
+export { Swiper } from './components/Swiper.js';
+export type { SwiperProps } from './components/Swiper.js';
+export {
+  useSwiperDotProgress,
+  useSwiperDotScale,
+  useSwiperDotGrowX,
+  useSwiperDotWidth,
+  useSwiperDotTranslate,
+} from './use-swiper-dot-progress.js';
+export type {
+  SwiperDotHookInputs,
+  UseSwiperDotProgressOptions,
+  UseSwiperDotTranslateOptions,
+} from './use-swiper-dot-progress.js';
 
 // ScrollView ↔ child-gesture coordination (Phase 2.12.3). Public mostly so
 // custom gesture components can opt in to the same auto-yield behavior that
 // `<Draggable>` and `<Swipeable>` get for free.
-export { useScrollContext } from './scroll-context';
-export type { ScrollContext } from './scroll-context';
+export { useScrollContext } from './scroll-context.js';
+export type { ScrollContext } from './scroll-context.js';
 
 // Types
 export type {
@@ -58,4 +72,4 @@ export type {
   RotationState,
   UseRotationOptions,
   UseRotationReturn,
-} from './types';
+} from './types.js';

package/src/use-pinch.ts

@@ -1,6 +1,6 @@
 import { signal } from '@sigx/lynx';
-import type { UsePinchOptions, UsePinchReturn, TouchEvent, PinchState, TouchPoint } from './types';
-import { distance, midpoint } from './utils';
+import type { UsePinchOptions, UsePinchReturn, TouchEvent, PinchState, TouchPoint } from './types.js';
+import { distance, midpoint } from './utils.js';
 
 /**
  * Two-finger pinch/zoom gesture.

package/src/use-rotation.ts

@@ -5,8 +5,8 @@ import type {
   TouchEvent,
   TouchPoint,
   RotationState,
-} from './types';
-import { angle, angleDelta, distance, midpoint } from './utils';
+} from './types.js';
+import { angle, angleDelta, distance, midpoint } from './utils.js';
 
 /**
  * Two-finger rotation gesture.

package/src/use-swiper-dot-progress.ts

@@ -0,0 +1,231 @@
+/**
+ * Headless `<Swiper>` indicator hooks.
+ *
+ * `<Swiper>` writes the live scroll offset to a `SharedValue<number>` on
+ * the MT thread every frame. To render an indicator the consumer needs
+ * one binding per element so `useAnimatedStyle` has a stable call-site —
+ * doing that inside `.map()` is fine (per-iteration call-sites are
+ * stable across renders), but the bookkeeping (range math, ref alloc)
+ * is fiddly and easy to get wrong.
+ *
+ * These hooks own the bookkeeping and return a `MainThreadRef` the
+ * caller spreads onto any element they want animated. That keeps the
+ * presentation in user-land (and in `@sigx/lynx-daisyui`'s themed
+ * `SwiperIndicator`) while logic lives here.
+ *
+ * Layering pattern mirrors the daisyui split:
+ *   - `@sigx/lynx-gestures` owns headless logic (this file + the
+ *     `<Swiper>` component itself).
+ *   - `@sigx/lynx-daisyui` ships themed `<SwiperIndicator>` variants
+ *     that consume these hooks and pick colours from `ThemeProvider`.
+ *
+ * @example Custom dot using the opacity hook
+ * ```tsx
+ * function MyDot({ offset, pageWidth, index }) {
+ *   const ref = useSwiperDotProgress({ offset, pageWidth, index });
+ *   return (
+ *     <view
+ *       main-thread:ref={ref}
+ *       style={{ width: '8px', height: '8px', borderRadius: '4px',
+ *                backgroundColor: 'tomato', opacity: '0' }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+import {
+  useAnimatedStyle,
+  useMainThreadRef,
+  type MainThread,
+  type MainThreadRef,
+  type SharedValue,
+  type MapperParams,
+} from '@sigx/lynx';
+
+/** Common per-dot inputs — offset is page-pixel space, index is the dot's page. */
+export interface SwiperDotHookInputs {
+  /** Live MT-thread pixel offset from the Swiper's `offset` prop. */
+  offset: SharedValue<number>;
+  /** Page width in CSS pixels. Must match the Swiper's effective page width. */
+  pageWidth: number;
+  /** Zero-based page index this dot represents. */
+  index: number;
+}
+
+export interface UseSwiperDotProgressOptions extends SwiperDotHookInputs {
+  /**
+   * Half-width of the input window in `pageWidth` units. The dot's
+   * animation runs from `(index − window) * pageWidth` to
+   * `(index + window) * pageWidth`. Default `1` — adjacent dots
+   * crossfade because their windows overlap.
+   */
+  window?: number;
+  /**
+   * Output values at `[centre − window·pageWidth, centre, centre +
+   * window·pageWidth]`. Default `[0, 1, 0]` (triangular). For "always
+   * active" decoration use `[0, 1, 0]` with opacity; for "scale
+   * pulse" pass e.g. `[1, 1.4, 1]` with channel `'scale'`.
+   */
+  outputRange?: readonly [number, number, number];
+}
+
+/**
+ * Build a triangular range-map for the given dot index, defaulting to
+ * the opacity crossfade `<SwiperDots>` shipped with previously. Returns
+ * a `MainThreadRef` — spread it onto whatever element you want
+ * animated.
+ */
+export function useSwiperDotProgress(
+  opts: UseSwiperDotProgressOptions,
+): MainThreadRef<MainThread.Element | null> {
+  return useSwiperDotChannel({
+    ...opts,
+    channel: 'opacity',
+    outputRange: opts.outputRange ?? [0, 1, 0],
+  });
+}
+
+/**
+ * Scale-pulse variant — active dot scales up, neighbours scale down to
+ * the inactive baseline. Defaults: inactive `1`, active `1.4`.
+ *
+ * Uniform scale (both axes). For width-axis only growth (pill effect
+ * that keeps the dot's height stable) use `useSwiperDotGrowX` instead.
+ */
+export function useSwiperDotScale(opts: SwiperDotHookInputs & {
+  inactive?: number;
+  active?: number;
+  window?: number;
+}): MainThreadRef<MainThread.Element | null> {
+  const inactive = opts.inactive ?? 1;
+  const active = opts.active ?? 1.4;
+  return useSwiperDotChannel({
+    offset: opts.offset,
+    pageWidth: opts.pageWidth,
+    index: opts.index,
+    window: opts.window,
+    channel: 'scale',
+    outputRange: [inactive, active, inactive],
+  });
+}
+
+/**
+ * Width-axis growth — the active dot stretches into a pill, neighbours
+ * shrink to a circle. Uses the `scaleX` channel, so the element's
+ * intrinsic size in the layout stays put; only the visual width
+ * changes. If you want surrounding siblings to physically shove apart
+ * use `useSwiperDotWidth` instead (it animates the `width` style
+ * property, which costs a layout pass each frame).
+ */
+export function useSwiperDotGrowX(opts: SwiperDotHookInputs & {
+  /** Width multiplier when inactive. Default `1` (the dot's base size). */
+  inactive?: number;
+  /** Width multiplier when active. Default `3` (a pill ~3× as wide as tall). */
+  active?: number;
+  window?: number;
+}): MainThreadRef<MainThread.Element | null> {
+  const inactive = opts.inactive ?? 1;
+  const active = opts.active ?? 3;
+  return useSwiperDotChannel({
+    offset: opts.offset,
+    pageWidth: opts.pageWidth,
+    index: opts.index,
+    window: opts.window,
+    channel: 'scaleX',
+    outputRange: [inactive, active, inactive],
+  });
+}
+
+/**
+ * Layout-aware width growth — animates the element's `width` style in
+ * px. Use this when sibling layout must respond (siblings flex away as
+ * the pill grows). Slower than `useSwiperDotGrowX` because every frame
+ * re-runs layout.
+ *
+ * Defaults shape an 8px → 24px pill.
+ */
+export function useSwiperDotWidth(opts: SwiperDotHookInputs & {
+  /** Width in CSS pixels when inactive. Default `8`. */
+  inactive?: number;
+  /** Width in CSS pixels when active. Default `24`. */
+  active?: number;
+  window?: number;
+}): MainThreadRef<MainThread.Element | null> {
+  const inactive = opts.inactive ?? 8;
+  const active = opts.active ?? 24;
+  return useSwiperDotChannel({
+    offset: opts.offset,
+    pageWidth: opts.pageWidth,
+    index: opts.index,
+    window: opts.window,
+    channel: 'width',
+    outputRange: [inactive, active, inactive],
+  });
+}
+
+/** Inputs for the track-wide translate hook used by the "bar" indicator variant. */
+export interface UseSwiperDotTranslateOptions {
+  offset: SharedValue<number>;
+  /** Page width in CSS pixels. */
+  pageWidth: number;
+  /**
+   * Distance in CSS pixels that one full page of scroll should move
+   * the thumb by — typically `dotWidth + spacing` (the thumb steps to
+   * the next dot's centre when the swiper advances by one page).
+   */
+  step: number;
+}
+
+/**
+ * Translate a single "thumb" element across the indicator track,
+ * proportional to the swiper's scroll progress. Use for the `bar`
+ * variant where a single pill slides between fixed dots.
+ */
+export function useSwiperDotTranslate(
+  opts: UseSwiperDotTranslateOptions,
+): MainThreadRef<MainThread.Element | null> {
+  const ref = useMainThreadRef<MainThread.Element | null>(null);
+  // factor = step px per pageWidth px of offset. Guard against the
+  // divide-by-zero before first layout — a factor of 0 just parks the
+  // thumb at translateX(0), which is the correct initial position.
+  const factor = opts.pageWidth > 0 ? opts.step / opts.pageWidth : 0;
+  useAnimatedStyle(ref, opts.offset, 'translateX', { factor });
+  return ref;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Internals
+
+/**
+ * Channels with `RangeParams` support that the indicator hooks use.
+ * `width` / `height` run via the new layout-axis mappers; `scaleX` /
+ * `scale` / `opacity` are transform/opacity-only.
+ */
+type RangeChannel = 'opacity' | 'scale' | 'scaleX' | 'scaleY' | 'translateX' | 'translateY' | 'width' | 'height';
+
+interface ChannelOptions<N extends RangeChannel> extends SwiperDotHookInputs {
+  channel: N;
+  outputRange: readonly [number, number, number];
+  window?: number;
+}
+
+function useSwiperDotChannel<N extends RangeChannel>(
+  opts: ChannelOptions<N>,
+): MainThreadRef<MainThread.Element | null> {
+  const ref = useMainThreadRef<MainThread.Element | null>(null);
+  // Guard against pre-layout pageWidth=0: collapsing the inputRange to
+  // [0, 0, 0] would produce divide-by-zero / NaN in interpolateLinear.
+  // Fall back to a non-degenerate window so the binding stays valid; once
+  // layout settles and the parent re-renders with a real pageWidth, the
+  // values flow through normally.
+  const safePageWidth = opts.pageWidth > 0 ? opts.pageWidth : 1;
+  const center = opts.index * safePageWidth;
+  const w = (opts.window ?? 1) * safePageWidth;
+  const params: MapperParams[N] = {
+    inputRange: [center - w, center, center + w],
+    outputRange: [opts.outputRange[0], opts.outputRange[1], opts.outputRange[2]],
+    extrapolate: 'clamp',
+  } as MapperParams[N];
+  useAnimatedStyle(ref, opts.offset, opts.channel, params);
+  return ref;
+}