@glasshome/widget-sdk 0.3.6 → 0.3.7

package/dist/framework/gestures/haptics.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Haptic feedback for gesture transitions.
+ *
+ * Resolution order at runtime:
+ *   1. Capacitor Haptics plugin (Android/iOS native) — richer patterns
+ *   2. `navigator.vibrate` (Android Chrome/WebView)
+ *   3. silent (desktop, iOS Safari)
+ *
+ * No build-time dependency on @capacitor/haptics — the host app installs the
+ * plugin; we probe `window.Capacitor.Plugins.Haptics` at call time.
+ */
+export declare const haptics: {
+    /** Light confirmation — fires when slide gesture arms after user holds still. */
+    tick(): void;
+    /** Medium bump — fires when hold gesture commits (detail opening). */
+    bump(): void;
+    /** Stronger pulse — reserved for edit-mode pickup (future use). */
+    pulse(): void;
+};

package/dist/framework/gestures/use-widget-gestures.d.ts

@@ -1,32 +1,22 @@
 /**
- * Widget Gestures Hook
+ * Widget Gestures Hook — Mobile-aware
  *
- * Provides gesture handling for widgets with automatic conflict resolution.
- * Ported from React reference, adapted for SolidJS:
- * - Uses mutable state object instead of useRef (imperative gesture tracking)
- * - Accepts config/orientation as accessors for reactivity
- * - Returns native PointerEvent handlers (not React.PointerEvent)
- * - Callers bind via on:pointerdown={handlers.onPointerDown}
+ * Two grammars by pointer type:
  *
- * @example
- * ```tsx
- * const gestures = useWidgetGestures(
- *   () => ({
- *     tap: handleTap,
- *     hold: { action: handleHold, delay: 300 },
- *     slide: {
- *       value: brightness(),
- *       onChange: setBrightness,
- *       min: 0,
- *       max: 100,
- *       orientation: "auto",
- *     },
- *   }),
- *   () => ctx.orientation(),
- * );
+ *   TOUCH (phone, tablet):
+ *     - tap    → primary action
+ *     - hold   → detail dialog (with haptic bump)
+ *     - slide  → DISABLED. Fine control lives in the detail dialog instead.
+ *     This eliminates the slide-vs-page-scroll conflict that makes mobile
+ *     gestures fragile. `touch-action: manipulation` ensures the browser
+ *     handles scroll natively without our interference.
  *
- * return <div on:pointerdown={gestures.onPointerDown} on:pointermove={gestures.onPointerMove} on:pointerup={gestures.onPointerUp} on:pointercancel={gestures.onPointerCancel}>...</div>;
- * ```
+ *   MOUSE / PEN (desktop, hybrid devices):
+ *     - tap, hold, slide all active. Slide arms immediately on pointerdown —
+ *     no scroll conflict to worry about (mouse uses wheel for scroll).
+ *
+ * Pointer type is decided per press at pointerdown. A hybrid device (tablet
+ * + bluetooth mouse) gets the right grammar based on which input fired.
  */
 import type { GestureConfig, WidgetOrientation } from "../types";
 export interface GestureHandlers {
@@ -43,24 +33,12 @@ export interface GestureHandlers {
      */
     bindElement: (el: HTMLElement) => void;
     /**
-     * CSS `touch-action` value for the gesture root. Horizontal slide → `pan-y`
-     * (page scrolls vertically, slider owns horizontal). Vertical slide → `pan-x`.
-     * Tap/hold only → `manipulation`. Without this, mobile browsers cancel the
-     * pointer mid-slide once they decide the touch is a pan.
+     * CSS `touch-action` for the gesture root. Always `manipulation` when any
+     * gesture is configured — mobile slide is intentionally dropped, so the
+     * browser owns scroll completely on touch surfaces.
      */
     touchAction: () => string;
-    /** Cancel any pending hold/slide timers. Call on component unmount via onCleanup. */
+    /** Cancel any pending hold timer. Call on component unmount via onCleanup. */
     dispose: () => void;
 }
-/**
- * Widget gestures hook with conflict resolution
- *
- * Features:
- * - Axis locking: Once slide direction is detected, locks to that axis
- * - Scroll prevention: Blocks page scroll when sliding along widget axis
- * - Tap/hold/slide gesture support with automatic conflict resolution
- *
- * @param config - Accessor returning gesture configuration
- * @param orientation - Accessor returning widget orientation (for auto slide orientation)
- */
 export declare function useWidgetGestures(config: () => GestureConfig, orientation?: () => WidgetOrientation): GestureHandlers;