@object-ui/mobile 17.6.0 → 17.7.0

package/README.md

@@ -25,18 +25,22 @@ npm install @object-ui/mobile
 ## Quick Start
 
 ```tsx
-import { MobileProvider, useBreakpoint, useGesture } from '@object-ui/mobile';
+import { MobileProvider, useBreakpoint } from '@object-ui/mobile';
 
-function App() {
-  return (
-    <MobileProvider>
-      <ResponsiveApp />
-    </MobileProvider>
-  );
+function MobileNav() {
+  return <nav>Mobile navigation</nav>;
+}
+
+function DesktopSidebar() {
+  return <aside>Desktop sidebar</aside>;
+}
+
+function MainContent() {
+  return <main>Main content</main>;
 }
 
 function ResponsiveApp() {
-  const { isMobile, isTablet, isDesktop } = useBreakpoint();
+  const { isMobile, isDesktop } = useBreakpoint();
 
   return (
     <div>
@@ -46,84 +50,229 @@ function ResponsiveApp() {
     </div>
   );
 }
+
+export function App() {
+  return (
+    <MobileProvider>
+      <ResponsiveApp />
+    </MobileProvider>
+  );
+}
 ```
 
 ## API
 
 ### MobileProvider
 
-Wraps your application with mobile context:
+Wraps your application with mobile context. Both props are optional: `pwa` takes a
+`PWAConfig`, `offline` takes a `PWAOfflineConfig`.
 
 ```tsx
-<MobileProvider>
-  <App />
-</MobileProvider>
+import { MobileProvider } from '@object-ui/mobile';
+
+function App() {
+  return <p>Your application</p>;
+}
+
+export function Root() {
+  return (
+    <MobileProvider>
+      <App />
+    </MobileProvider>
+  );
+}
 ```
 
 ### useBreakpoint
 
-Hook for detecting the current breakpoint:
+Hook for detecting the current breakpoint. The current breakpoint name is
+`breakpoint` — one of `xs`, `sm`, `md`, `lg`, `xl`, `2xl`:
 
 ```tsx
-const { isMobile, isTablet, isDesktop, current } = useBreakpoint();
+import { useBreakpoint } from '@object-ui/mobile';
+
+export function BreakpointBadge() {
+  const { isMobile, isTablet, isDesktop, breakpoint, width } = useBreakpoint();
+
+  return (
+    <span>
+      {breakpoint} at {width}px — mobile {String(isMobile)}, tablet {String(isTablet)}, desktop{' '}
+      {String(isDesktop)}
+    </span>
+  );
+}
 ```
 
+`isAbove(bp)` and `isBelow(bp)` are also returned, for comparisons against a named
+breakpoint.
+
 ### useResponsive
 
-Hook for responsive values based on screen size:
+Hook for responsive values based on screen size. The keys are breakpoint names; a
+breakpoint with no entry falls back to the next smaller one that has one:
 
 ```tsx
-const columns = useResponsive({ mobile: 1, tablet: 2, desktop: 4 });
+import { useResponsive } from '@object-ui/mobile';
+
+export function ResponsiveGrid() {
+  const columns = useResponsive({ xs: 1, md: 2, lg: 4 });
+
+  return <div data-columns={columns}>{columns} column(s)</div>;
+}
 ```
 
 ### useGesture / useSpecGesture
 
-Hooks for gesture detection on touch devices:
+`useGesture` detects one gesture from Object UI's direction-fused vocabulary
+(`tap`, `double-tap`, `long-press`, `swipe-left`, `swipe-right`, `swipe-up`,
+`swipe-down`, `pinch`, `rotate`, `pan`) per call, and returns a ref to attach:
 
 ```tsx
-const gestureRef = useGesture({
-  onSwipeLeft: () => navigateNext(),
-  onSwipeRight: () => navigateBack(),
-  onPinch: (scale) => handleZoom(scale),
-});
+import { useGesture } from '@object-ui/mobile';
+
+function navigateNext() {}
+function navigateBack() {}
+
+export function SwipeArea() {
+  const nextRef = useGesture<HTMLDivElement>({
+    type: 'swipe-left',
+    onGesture: () => navigateNext(),
+  });
+  const backRef = useGesture<HTMLDivElement>({
+    type: 'swipe-right',
+    onGesture: () => navigateBack(),
+  });
+
+  return (
+    <div>
+      <div ref={nextRef}>Swipe left for the next record</div>
+      <div ref={backRef}>Swipe right to go back</div>
+    </div>
+  );
+}
+```
+
+`useSpecGesture` takes the declarative `SpecGestureConfig` tuning shape instead, and
+dispatches to per-gesture callbacks:
+
+```tsx
+import { useSpecGesture } from '@object-ui/mobile';
+
+function handleZoom(scale: number) {
+  return scale;
+}
 
-return <div ref={gestureRef}>Swipeable content</div>;
+export function PinchArea() {
+  const ref = useSpecGesture<HTMLDivElement>({
+    config: { type: 'pinch', enabled: true, pinch: { minScale: 0.5, maxScale: 3 } },
+    onPinch: (scale) => handleZoom(scale),
+  });
+
+  return <div ref={ref}>Pinchable content</div>;
+}
 ```
 
 ### usePullToRefresh
 
-Hook for pull-to-refresh behavior:
+Hook for pull-to-refresh behavior. Attach the returned `ref` to the scrollable
+container:
 
 ```tsx
-const { isRefreshing } = usePullToRefresh({
-  onRefresh: async () => await fetchData(),
-});
+import { usePullToRefresh } from '@object-ui/mobile';
+
+async function fetchData(): Promise<void> {}
+
+export function Feed() {
+  const { ref, isRefreshing, pullDistance } = usePullToRefresh<HTMLDivElement>({
+    onRefresh: async () => await fetchData(),
+  });
+
+  return (
+    <div ref={ref} data-pull-distance={pullDistance}>
+      {isRefreshing ? 'Refreshing…' : 'Pull to refresh'}
+    </div>
+  );
+}
 ```
 
+The element does not have to exist on the first render. A component that shows
+a loading screen first and attaches `ref` once its data arrives works, and so
+does one that later swaps in a new element. The hook binds its touch listeners
+to whatever element `ref` points at after each render.
+
+Pull hosts can nest, for example a list view that renders a grid view inside
+it. One pull belongs to the outermost armed host: an inner host lets the
+gesture go when an armed pull host sits above it in the DOM, so a single pull
+draws one indicator and runs one `onRefresh`.
+
 ### useTouchTarget
 
-Hook for ensuring minimum touch target sizes:
+Hook for ensuring minimum touch target sizes. It returns the `style` and `className`
+to spread onto the element; the defaults follow WCAG 2.5.5 (44×44 CSS pixels):
 
 ```tsx
-const { targetProps } = useTouchTarget({ minSize: 44 });
-return <button {...targetProps}>Tap me</button>;
+import { useTouchTarget } from '@object-ui/mobile';
+
+export function TapButton() {
+  const { style, className } = useTouchTarget({
+    config: { minWidth: 44, minHeight: 44 },
+  });
+
+  return (
+    <button style={style} className={className}>
+      Tap me
+    </button>
+  );
+}
 ```
 
 ### ResponsiveContainer
 
-Renders children based on breakpoint:
+Renders children based on breakpoint. Pick the range with `minBreakpoint` /
+`maxBreakpoint`, or name the breakpoints outright with `showOn` / `hideOn`:
 
 ```tsx
-<ResponsiveContainer mobile={<MobileView />} desktop={<DesktopView />} />
+import { ResponsiveContainer } from '@object-ui/mobile';
+
+function MobileView() {
+  return <p>Compact layout</p>;
+}
+
+function DesktopView() {
+  return <p>Full layout</p>;
+}
+
+export function BreakpointSwitch() {
+  return (
+    <div>
+      <ResponsiveContainer maxBreakpoint="md">
+        <MobileView />
+      </ResponsiveContainer>
+      <ResponsiveContainer minBreakpoint="lg">
+        <DesktopView />
+      </ResponsiveContainer>
+    </div>
+  );
+}
 ```
 
 ### PWA Utilities
 
+`PWAConfig` requires `enabled`, `name` and `shortName`. `registerServiceWorker` takes
+the script `url` and `scope` plus lifecycle callbacks — the caching strategies live in
+the generated worker (`getServiceWorkerSource`), not in this call:
+
 ```tsx
 import { generatePWAManifest, registerServiceWorker } from '@object-ui/mobile';
 
-const manifest = generatePWAManifest({ name: 'My App', themeColor: '#000' });
-registerServiceWorker({ cacheStrategy: 'network-first' });
+export const manifest = generatePWAManifest({
+  enabled: true,
+  name: 'My App',
+  shortName: 'My App',
+  themeColor: '#000',
+});
+
+void registerServiceWorker({ url: '/service-worker.js' });
 ```
 
 ## Links

package/dist/index.d.ts

@@ -19,7 +19,6 @@
  */
 export { useBreakpoint, type BreakpointState } from './useBreakpoint.js';
 export { useResponsive } from './useResponsive.js';
-export { useResponsiveConfig, type SpecResponsiveConfig, type ResolvedResponsiveState } from './useResponsiveConfig.js';
 export { useGesture, type UseGestureOptions } from './useGesture.js';
 export { useSpecGesture, type UseSpecGestureOptions } from './useSpecGesture.js';
 export { useTouchTarget, type UseTouchTargetOptions, type TouchTargetResult } from './useTouchTarget.js';
@@ -33,5 +32,5 @@ export { createOfflineDataSource, type OfflineDataSource, type OfflineDataSource
 export { useOfflineSync, type OfflineSyncState } from './useOfflineSync.js';
 export { getServiceWorkerSource, requestBackgroundSync, type ServiceWorkerSourceOptions, } from './serviceWorkerSource.js';
 export { BREAKPOINTS, resolveResponsiveValue } from './breakpoints.js';
-export type { BreakpointName, ResponsiveValue, MobileResponsiveConfig, PWAConfig, PWAIcon, FetchCacheStrategy, PWAOfflineConfig, OfflineRoute, GestureType, GestureConfig, GestureContext, MobileComponentConfig, SpecGestureConfig, SwipeGestureConfig, PinchGestureConfig, LongPressGestureConfig, TouchInteraction, TouchTargetConfig, } from '@object-ui/types';
+export type { BreakpointName, ResponsiveValue, PWAConfig, PWAIcon, FetchCacheStrategy, PWAOfflineConfig, OfflineRoute, GestureType, GestureContext, SpecGestureConfig, SwipeGestureConfig, PinchGestureConfig, LongPressGestureConfig, TouchInteraction, TouchTargetConfig, } from '@object-ui/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,KAAK,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACxH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACzG,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,KAAK,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,GACzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAGvE,YAAY,EACV,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,SAAS,EACT,OAAO,EACP,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAQnD,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACzG,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,KAAK,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,GACzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAGvE,YAAY,EACV,cAAc,EACd,eAAe,EAMf,SAAS,EACT,OAAO,EACP,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -19,7 +19,13 @@
  */
 export { useBreakpoint } from './useBreakpoint.js';
 export { useResponsive } from './useResponsive.js';
-export { useResponsiveConfig } from './useResponsiveConfig.js';
+// `useResponsiveConfig` REMOVED (objectui#7580, maintainer ruling 2026-09-04).
+// It read `@objectstack/spec`'s `ResponsiveConfigSchema`, which objectstack#11027
+// retired; it was measured at zero callers on objectui#4773. Its exported
+// `SpecResponsiveConfig` / `ResolvedResponsiveState` went with it — both named
+// the retired schema's shape and neither had a reader. No behaviour is retired:
+// the live per-breakpoint readers are `useBreakpoint` and
+// `ResponsiveContainer` below, which are untouched.
 export { useGesture } from './useGesture.js';
 export { useSpecGesture } from './useSpecGesture.js';
 export { useTouchTarget } from './useTouchTarget.js';

package/dist/usePullToRefresh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePullToRefresh.d.ts","sourceRoot":"","sources":["../src/usePullToRefresh.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAClE,OAAO,EAAE,oBAAoB;;;;EA+D9B"}
+{"version":3,"file":"usePullToRefresh.d.ts","sourceRoot":"","sources":["../src/usePullToRefresh.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAClE,OAAO,EAAE,oBAAoB;;;;EAoG9B"}

package/dist/usePullToRefresh.js

@@ -50,18 +50,103 @@ export function usePullToRefresh(options) {
             }
         }
     }, [enabled, isRefreshing, pullDistance, threshold, onRefresh]);
+    /**
+     * The listeners follow the ELEMENT, not the mount (objectui#10105).
+     *
+     * `ref` is an object ref, so nothing tells this hook when a consumer
+     * attaches it. The binding used to live in an effect keyed on the handlers
+     * and `enabled`, which read `ref.current` once and then waited for one of
+     * those to change. A consumer whose first commit is a loading screen has
+     * `ref.current === null` at that moment. When the real host appears later,
+     * none of those keys has changed, so the effect never ran again and the
+     * gesture was dead. The consumers that do this, and the ones that do not,
+     * were measured on objectui#10105; the list is not repeated here because it
+     * would go stale. The same happened when a refresh put the loading screen
+     * back and the host came back as a NEW element: the listeners stayed on the
+     * old, detached one.
+     *
+     * So the binding effect below has no dependency list and runs after every
+     * commit. It re-binds only when the element it SHOULD be bound to
+     * (`ref.current`, or `null` while disabled) differs from the one it IS bound
+     * to. That is a DOM-identity comparison, never a comparison of memoised
+     * identities (AGENTS.md §5 #10). The native listeners stay the same for the
+     * life of a binding and call the latest handlers through `handlersRef`, so a
+     * state change such as each `pullDistance` step during a gesture no longer
+     * re-binds anything.
+     */
+    const handlersRef = useRef({ handleTouchStart, handleTouchMove, handleTouchEnd });
     useEffect(() => {
-        const el = ref.current;
-        if (!el || !enabled)
+        handlersRef.current = { handleTouchStart, handleTouchMove, handleTouchEnd };
+    });
+    const bindingRef = useRef(null);
+    useEffect(() => {
+        const target = enabled ? ref.current : null;
+        const bound = bindingRef.current;
+        if ((bound ? bound.el : null) === target)
             return;
-        el.addEventListener('touchstart', handleTouchStart, { passive: true });
-        el.addEventListener('touchmove', handleTouchMove, { passive: true });
-        el.addEventListener('touchend', handleTouchEnd, { passive: true });
-        return () => {
-            el.removeEventListener('touchstart', handleTouchStart);
-            el.removeEventListener('touchmove', handleTouchMove);
-            el.removeEventListener('touchend', handleTouchEnd);
-        };
-    }, [handleTouchStart, handleTouchMove, handleTouchEnd, enabled]);
+        if (bound)
+            unbindPullListeners(bound);
+        bindingRef.current = target ? bindPullListeners(target, handlersRef) : null;
+    });
+    // Unmount. The per-commit effect above returns no cleanup on purpose, since
+    // a cleanup there would re-bind on every commit. This is where the last
+    // binding is released. It releases the exact listeners that were added,
+    // which are recorded on the binding, so nothing depends on an identity
+    // staying stable.
+    useEffect(() => () => {
+        const bound = bindingRef.current;
+        if (bound)
+            unbindPullListeners(bound);
+        bindingRef.current = null;
+    }, []);
     return { ref, isRefreshing, pullDistance };
 }
+/**
+ * One gesture, one owner: the OUTERMOST armed pull host (objectui#10105).
+ *
+ * Pull hosts nest. `ListView` has one, and so does the view it renders inside
+ * it. A touch on the inner host bubbles to the outer one, so without a rule
+ * both hooks drew an indicator and both ran their refresh for the same pull.
+ * The outer one is the owner: its single refetch reloads the rows the inner
+ * view was handed, and an inner view fed its rows by a parent has no refresh of
+ * its own to run.
+ *
+ * While bound, the hook marks its element with this attribute. It is a DOM
+ * attribute and not module state so that two copies of this package in one
+ * page still see each other. At `touchstart` an inner host looks for a marked
+ * ANCESTOR, and if one is armed it lets the gesture go: it never records a
+ * start point, so its move and end handlers do nothing for this gesture. The
+ * native listeners and the DOM ancestry are the same relation (the outer
+ * listener receives this event because it is an ancestor), which is why the
+ * check reads the DOM and not the React tree.
+ */
+const PULL_HOST_ATTRIBUTE = 'data-pull-to-refresh-host';
+function armedPullHostAbove(el) {
+    const parent = el.parentElement;
+    return parent !== null && parent.closest(`[${PULL_HOST_ATTRIBUTE}]`) !== null;
+}
+function bindPullListeners(el, handlers) {
+    const binding = {
+        el,
+        start: (e) => {
+            if (armedPullHostAbove(el))
+                return;
+            handlers.current.handleTouchStart(e);
+        },
+        move: (e) => handlers.current.handleTouchMove(e),
+        end: () => {
+            void handlers.current.handleTouchEnd();
+        },
+    };
+    el.setAttribute(PULL_HOST_ATTRIBUTE, '');
+    el.addEventListener('touchstart', binding.start, { passive: true });
+    el.addEventListener('touchmove', binding.move, { passive: true });
+    el.addEventListener('touchend', binding.end, { passive: true });
+    return binding;
+}
+function unbindPullListeners(binding) {
+    binding.el.removeAttribute(PULL_HOST_ATTRIBUTE);
+    binding.el.removeEventListener('touchstart', binding.start);
+    binding.el.removeEventListener('touchmove', binding.move);
+    binding.el.removeEventListener('touchend', binding.end);
+}

package/dist/useSpecGesture.d.ts

@@ -21,7 +21,10 @@ export interface UseSpecGestureOptions {
     onPan?: (direction: string) => void;
     /** Callback when a rotate gesture is detected (degrees, CW positive) */
     onRotate?: (rotation: number) => void;
-    /** Fallback for gestures without a dedicated callback */
+    /**
+     * Fallback for gestures without a dedicated callback. Its `type` is the
+     * DECLARED spec gesture, never the recognizer's own name for the same move.
+     */
     onGesture?: (context: {
         type: string;
         direction?: string;
@@ -35,8 +38,10 @@ export interface UseSpecGestureOptions {
  * {@link GestureType} `useGesture` implements. Note the two sides are
  * different vocabularies, which is why this map exists at all: the retired
  * spec's `drag` and `pan` are one recognizer
- * (any-direction move past the threshold); `swipe` resolves per configured
- * direction, so it maps through {@link SWIPE_DIRECTION_MAP} instead.
+ * (any-direction move past the threshold); `swipe` declares a SET of
+ * directions, so it recognizes on that same any-direction move and fires only
+ * when the DETECTED direction is a member of the declared set — no single
+ * recognizer name carries that, which is why its entry below is a placeholder.
  * Exported for the spec-parity test.
  *
  * Before #2942 the hook never read `config.type` at all — it branched on
@@ -47,13 +52,14 @@ export interface UseSpecGestureOptions {
 export declare const SPEC_GESTURE_TYPE_MAP: Record<string, GestureType>;
 /**
  * Spec-aware gesture hook that maps a {@link SpecGestureConfig} — the retired
- * `@objectstack/spec` `ui/touch` shape, not this package's own
- * `GestureConfig` — onto the existing useGesture hook.
+ * `@objectstack/spec` `ui/touch` tuning shape, a different contract from the
+ * direction-fused {@link GestureType} vocabulary `useGesture` speaks — onto
+ * the existing useGesture hook.
  *
  * @example
  * ```tsx
  * const ref = useSpecGesture({
- *   config: { type: 'swipe', enabled: true, swipe: { direction: 'left', threshold: 80 } },
+ *   config: { type: 'swipe', enabled: true, swipe: { direction: ['left'], threshold: 80 } },
  *   onSwipe: (dir) => console.log('Swiped', dir),
  * });
  * return <div ref={ref}>Swipe me</div>;

package/dist/useSpecGesture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSpecGesture.d.ts","sourceRoot":"","sources":["../src/useSpecGesture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,gDAAgD;IAChD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,gDAAgD;IAChD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,wEAAwE;IACxE,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,yDAAyD;IACzD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACxG;AASD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAQ7D,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAChE,OAAO,EAAE,qBAAqB,uCAoE/B"}
+{"version":3,"file":"useSpecGesture.d.ts","sourceRoot":"","sources":["../src/useSpecGesture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,MAAM,WAAW,qBAAqB;IACpC,iCAAiC;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,gDAAgD;IAChD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,gDAAgD;IAChD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,wEAAwE;IACxE,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACxG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAQ7D,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAChE,OAAO,EAAE,qBAAqB,uCAoF/B"}

package/dist/useSpecGesture.js

@@ -6,20 +6,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useGesture } from './useGesture.js';
-const SWIPE_DIRECTION_MAP = {
-    left: 'swipe-left',
-    right: 'swipe-right',
-    up: 'swipe-up',
-    down: 'swipe-down',
-};
 /**
  * `SPEC_GESTURE_TYPES` (the retired `ui/touch` vocabulary, owned by
  * `@object-ui/types` since objectstack#4988) → the recognizer
  * {@link GestureType} `useGesture` implements. Note the two sides are
  * different vocabularies, which is why this map exists at all: the retired
  * spec's `drag` and `pan` are one recognizer
- * (any-direction move past the threshold); `swipe` resolves per configured
- * direction, so it maps through {@link SWIPE_DIRECTION_MAP} instead.
+ * (any-direction move past the threshold); `swipe` declares a SET of
+ * directions, so it recognizes on that same any-direction move and fires only
+ * when the DETECTED direction is a member of the declared set — no single
+ * recognizer name carries that, which is why its entry below is a placeholder.
  * Exported for the spec-parity test.
  *
  * Before #2942 the hook never read `config.type` at all — it branched on
@@ -28,7 +24,7 @@ const SWIPE_DIRECTION_MAP = {
  * fell through to the `'tap'` initializer and fired on a tap.
  */
 export const SPEC_GESTURE_TYPE_MAP = {
-    swipe: 'swipe-left', // per-direction; resolved via SWIPE_DIRECTION_MAP
+    swipe: 'swipe-left', // placeholder; the hook recognizes any direction and filters by the declared set
     pinch: 'pinch',
     long_press: 'long-press',
     double_tap: 'double-tap',
@@ -38,13 +34,14 @@ export const SPEC_GESTURE_TYPE_MAP = {
 };
 /**
  * Spec-aware gesture hook that maps a {@link SpecGestureConfig} — the retired
- * `@objectstack/spec` `ui/touch` shape, not this package's own
- * `GestureConfig` — onto the existing useGesture hook.
+ * `@objectstack/spec` `ui/touch` tuning shape, a different contract from the
+ * direction-fused {@link GestureType} vocabulary `useGesture` speaks — onto
+ * the existing useGesture hook.
  *
  * @example
  * ```tsx
  * const ref = useSpecGesture({
- *   config: { type: 'swipe', enabled: true, swipe: { direction: 'left', threshold: 80 } },
+ *   config: { type: 'swipe', enabled: true, swipe: { direction: ['left'], threshold: 80 } },
  *   onSwipe: (dir) => console.log('Swiped', dir),
  * });
  * return <div ref={ref}>Swipe me</div>;
@@ -69,15 +66,34 @@ export function useSpecGesture(options) {
     let threshold;
     let longPressDuration;
     let onGesture = () => { };
+    // `type` goes LAST in every payload below. The recognizer's own `type`
+    // travels inside `ctx` at runtime (`GestureContext.type`), so a `type`
+    // written BEFORE the spread is overwritten by it and the callback reports the
+    // recognizer instead of the declared spec gesture (objectui#9691). The two
+    // are different vocabularies — see `SPEC_GESTURE_TYPE_MAP` — so they agree
+    // only by coincidence, arm by arm.
     const fallback = (ctx) => onAny?.(ctx);
     switch (declared) {
         case 'swipe': {
-            const dir = Array.isArray(config.swipe?.direction)
-                ? config.swipe?.direction[0]
-                : config.swipe?.direction;
-            gestureType = (dir ? SWIPE_DIRECTION_MAP[dir] : undefined) ?? 'swipe-left';
+            // `SwipeGestureConfig.direction` is declared as a SET
+            // (`SpecSwipeDirection[]`), so recognition is the any-direction move past
+            // the threshold and the swipe fires only when the DETECTED direction is a
+            // MEMBER of that set. `direction[0]` would honour one element of a declared
+            // many; a scalar `direction` is rejected by the declared type and nothing
+            // re-admits it here (AGENTS.md #0.1). An empty or absent set declares no
+            // direction, so it fires for none.
+            const declaredDirections = config.swipe?.direction ?? [];
+            gestureType = 'pan';
             threshold = config.swipe?.threshold;
-            onGesture = (ctx) => (onSwipe ? onSwipe(ctx.direction ?? dir ?? 'left') : fallback({ type: 'swipe', ...ctx }));
+            onGesture = (ctx) => {
+                const detected = ctx.direction;
+                if (detected === undefined || !declaredDirections.includes(detected))
+                    return;
+                if (onSwipe)
+                    onSwipe(detected);
+                else
+                    fallback({ ...ctx, type: 'swipe' });
+            };
             break;
         }
         case 'long_press':
@@ -87,7 +103,7 @@ export function useSpecGesture(options) {
             break;
         case 'pinch':
             gestureType = 'pinch';
-            onGesture = (ctx) => (onPinch ? onPinch(ctx.scale ?? 1) : fallback({ type: 'pinch', ...ctx }));
+            onGesture = (ctx) => (onPinch ? onPinch(ctx.scale ?? 1) : fallback({ ...ctx, type: 'pinch' }));
             break;
         case 'double_tap':
             gestureType = 'double-tap';
@@ -96,11 +112,11 @@ export function useSpecGesture(options) {
         case 'pan':
         case 'drag':
             gestureType = 'pan';
-            onGesture = (ctx) => (onPan ? onPan(ctx.direction ?? 'left') : fallback({ type: declared, ...ctx }));
+            onGesture = (ctx) => (onPan ? onPan(ctx.direction ?? 'left') : fallback({ ...ctx, type: declared }));
             break;
         case 'rotate':
             gestureType = 'rotate';
-            onGesture = (ctx) => (onRotate ? onRotate(ctx.rotation ?? 0) : fallback({ type: 'rotate', ...ctx }));
+            onGesture = (ctx) => (onRotate ? onRotate(ctx.rotation ?? 0) : fallback({ ...ctx, type: 'rotate' }));
             break;
         default:
             break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/mobile",
-  "version": "17.6.0",
+  "version": "17.7.0",
   "type": "module",
   "license": "MIT",
   "description": "Mobile optimization for Object UI with responsive components, PWA support, and touch gesture handling.",
@@ -30,7 +30,7 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@object-ui/types": "17.6.0"
+    "@object-ui/types": "17.7.0"
   },
   "devDependencies": {
     "@objectstack/spec": "^17.0.0",
@@ -61,9 +61,9 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
-    "test": "vitest run",
+    "build": "tsc && node ../../scripts/check-dist-completeness.mjs",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "test": "vitest run --root ../.. packages/mobile/",
     "type-check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "lint": "eslint ."
   }