@lynx-example/design-guide 0.3.1 → 0.4.0

package/src/force_field/field.types.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from "@lynx-js/react";
-import type { LayoutChangeEvent, TouchEvent } from "@lynx-js/types";
+import type { LayoutChangeEvent, MouseEvent, TouchEvent } from "@lynx-js/types";
 
 type DotProps = {
   /** Normalized x position in the field (0..1). */
@@ -37,12 +37,15 @@ type DotFieldProps = {
   /** Field children (dots or other field-aware elements). */
   children?: ReactNode;
 
-  /** Pointer / touch handlers bound at the field level. */
+  /** Pointer (touch/mouse) handlers bound at the field level. */
   bindtouchstart?: (e: TouchEvent) => void;
   bindtouchmove?: (e: TouchEvent) => void;
   bindtouchend?: (e: TouchEvent) => void;
   bindtouchcancel?: (e: TouchEvent) => void;
 
+  bindmousedown?: (e: MouseEvent) => void;
+  bindmousemove?: (e: MouseEvent) => void;
+  bindmouseup?: (e: MouseEvent) => void;
   /** Layout measurement handler for field coordinate mapping. */
   bindlayoutchange?: (e: LayoutChangeEvent) => void;
 };

package/src/force_field/index.tsx

@@ -2,7 +2,7 @@ import { root } from "@lynx-js/react";
 import { useMemo } from "@lynx-js/react";
 
 import { Caption } from "../shared/components/caption/index.jsx";
-import { usePointerFieldPoint } from "../shared/hooks/use-pointer-field-point/index.js";
+import { usePointerPoint } from "../shared/hooks/use-pointer-point/index.js";
 import { CELLS } from "./cells.js";
 import { lerpColor } from "./color.js";
 import { makeForceField } from "./field-force.js";
@@ -24,11 +24,8 @@ const forceAt = makeForceField({
 function App() {
   const {
     p, // Force point in normalized space
-    handlePointerDown,
-    handlePointerMove,
-    handlePointerUp,
-    handleElementLayoutChange,
-  } = usePointerFieldPoint({ x0: 0.6, y0: 1 });
+    bind, // Spreadable interaction bindings (touch + mouse + layout)
+  } = usePointerPoint({ x0: 0.6, y0: 1 });
 
   const models = useMemo(() => {
     let minD = Infinity;
@@ -68,10 +65,7 @@ function App() {
         fieldSize={300}
         dotSize={5}
         dotAccentColor="#ff1a6e"
-        bindtouchstart={handlePointerDown}
-        bindtouchmove={handlePointerMove}
-        bindtouchend={handlePointerUp}
-        bindlayoutchange={handleElementLayoutChange}
+        {...bind}
       >
         {models.map((m) => (
           <Dot

package/src/gooey_effect/index.css

@@ -1,16 +1,26 @@
+/*
+ * Gooey Effect (blur + contrast)
+ *
+ * Visual output depends on each platform’s graphics pipeline:
+ * - Web renders a precise, crisp Gaussian blur.
+ * - iOS appears softer and more diffused.
+ * - Android may exhibit minor geometric artifacts on small surfaces
+ *   (e.g. a diamond-shaped silhouette) due to blur and downsampling.
+ *
+ * Blur is applied at the container level to reduce per-element artifacts.
+ */
+
 .stage {
-  filter: contrast(100);
-  /* background color must be explicit, for contrast */
+  filter: contrast(5);
+  /* Background color must be explicit for contrast-based thresholding */
   background-color: black;
-
   width: 100%;
   height: 200px;
 }
 
-.inner-stage {
-  /* Lynx: only one filter function per declaration */
-  filter: blur(20px);
-
+.dots-container {
+  /* Apply blur at the group level to reduce per-element blur artifacts on some platforms */
+  filter: blur(12px);
   width: 100%;
   height: 100%;
   display: flex;
@@ -20,11 +30,11 @@
 }
 
 .dot {
-  width: 64px;
-  height: 64px;
-  border-radius: 32px;
+  /* Keep dots crisp; container-level blur produces the gooey merge */
+  width: 54px;
+  height: 54px;
+  border-radius: 999px;
   background: white;
-
   animation: blob 2200ms ease-in-out infinite;
 }
 
@@ -44,19 +54,19 @@
 
 @keyframes blob {
   0% {
-    transform: translateX(-24px) translateY(0px) scale(1.00);
+    transform: translateX(-18px) translateY(0px) scale(1.00);
   }
   25% {
-    transform: translateX(10px) translateY(-6px) scale(1.06);
+    transform: translateX(7.5px) translateY(-4.5px) scale(1.06);
   }
   50% {
-    transform: translateX(28px) translateY(0px) scale(1.00);
+    transform: translateX(21px) translateY(0px) scale(1.00);
   }
   75% {
-    transform: translateX(6px) translateY(6px) scale(0.98);
+    transform: translateX(4.5px) translateY(4.5px) scale(0.98);
   }
   100% {
-    transform: translateX(-24px) translateY(0px) scale(1.00);
+    transform: translateX(-18px) translateY(0px) scale(1.00);
   }
 }
 
@@ -73,7 +83,7 @@
   justify-content: center;
   align-items: center;
   background-color: black;
-  gap: 48px;
+  gap: 40px;
 
   padding-left: 0;
   padding-right: 0;

package/src/gooey_effect/index.tsx

@@ -7,7 +7,7 @@ function App() {
   return (
     <view className="design-container">
       <view className="stage">
-        <view className="inner-stage">
+        <view className="dots-container">
           <view className="dot g1" />
           <view className="dot g2" />
           <view className="dot g3" />

package/src/shared/hooks/use-element-frame/index.ts

@@ -0,0 +1,70 @@
+import { useRef } from "@lynx-js/react";
+import type { MutableRefObject } from "@lynx-js/react";
+import type { LayoutChangeEvent } from "@lynx-js/types";
+
+/**
+ * Element measurement frame.
+ *
+ * Maintains the element's screen-based bounding frame:
+ * - left / top (from boundingClientRect)
+ * - width / height (from layout change)
+ *
+ * Designed to be shared by multiple pointer axes
+ * to avoid duplicate layout queries.
+ */
+export type ElementFrame = {
+  /** Screen-based left offset */
+  leftRef: MutableRefObject<number | null>;
+
+  /** Screen-based top offset */
+  topRef: MutableRefObject<number | null>;
+
+  /** Element width (px) */
+  widthRef: MutableRefObject<number>;
+
+  /** Element height (px) */
+  heightRef: MutableRefObject<number>;
+};
+
+export type UseElementFrameReturnValue = ElementFrame & {
+  /** Bind to <view bindlayoutchange={...} /> */
+  handleLayoutChange: (e: LayoutChangeEvent) => void;
+};
+
+export function useElementFrame(): UseElementFrameReturnValue {
+  const leftRef = useRef<number | null>(null);
+  const topRef = useRef<number | null>(null);
+  const widthRef = useRef(0);
+  const heightRef = useRef(0);
+
+  const handleLayoutChange = (e: LayoutChangeEvent) => {
+    // Sync element size from layout event
+    widthRef.current = e.detail.width;
+    heightRef.current = e.detail.height;
+
+    // Query screen-based bounding rect
+    const currentTarget = lynx
+      .createSelectorQuery()
+      // @ts-expect-error Lynx internal UID typing
+      .selectUniqueID(e.currentTarget.uid ?? e.currentTarget.uniqueId);
+
+    currentTarget
+      ?.invoke({
+        method: "boundingClientRect",
+        params: { relativeTo: "screen" },
+        success: (res: { left: number; top: number }) => {
+          leftRef.current = res.left;
+          topRef.current = res.top;
+        },
+      })
+      .exec();
+  };
+
+  return {
+    leftRef,
+    topRef,
+    widthRef,
+    heightRef,
+    handleLayoutChange,
+  };
+}

package/src/shared/hooks/use-pointer-axis/index.ts

@@ -0,0 +1,90 @@
+import { useRef } from "@lynx-js/react";
+import type { LayoutChangeEvent, TouchEvent } from "@lynx-js/types";
+import { useElementFrame } from "../use-element-frame/index.js";
+import type { PointerAxisPosition, UsePointerAxisProps, UsePointerAxisReturnValueBase } from "./types.js";
+
+/**
+ * Pointer → element-local coordinates adapter (single axis, X).
+ *
+ * - The container usually hosts touch/pointer events (recommended for larger hit area).
+ * - The element provides the measurement frame (layout + bounding rect).
+ * - If you don't need a separate container, you may bind all handlers on the element
+ *   itself (container === element).
+ *
+ * No clamping/step logic is applied here.
+ */
+function usePointerAxis({
+  axis = "x",
+  onUpdate,
+  onCommit,
+  frame: externalFrame,
+}: UsePointerAxisProps = {}): UsePointerAxisReturnValue {
+  /** Element (coordinate frame) & metrics */
+
+  const internalFrameRef = useElementFrame();
+  const frame = externalFrame ?? internalFrameRef;
+
+  const posRef = useRef<PointerAxisPosition | null>(null);
+  const draggingRef = useRef(false);
+
+  const pickCoord = (e: TouchEvent) => (axis === "x" ? e.detail.x : e.detail.y);
+
+  const startRef = axis === "x" ? frame.leftRef : frame.topRef;
+  const lengthRef = axis === "x" ? frame.widthRef : frame.heightRef;
+
+  const buildPosition = (coord: number): PointerAxisPosition | null => {
+    const length = lengthRef.current;
+    const start = startRef.current;
+
+    if (length > 0 && start != null) {
+      const offset = coord - start;
+      const offsetRatio = offset / length;
+      const pos = { offset, offsetRatio, elementLength: length };
+      posRef.current = pos;
+      return pos;
+    }
+    return null;
+  };
+
+  const handlePointerDown = (e: TouchEvent) => {
+    draggingRef.current = true;
+    buildPosition(pickCoord(e));
+    if (posRef.current) onUpdate?.(posRef.current);
+  };
+
+  const handlePointerMove = (e: TouchEvent) => {
+    if (!draggingRef.current) return;
+    buildPosition(pickCoord(e));
+    if (posRef.current) onUpdate?.(posRef.current);
+  };
+
+  const handlePointerUp = (e: TouchEvent) => {
+    draggingRef.current = false;
+    buildPosition(pickCoord(e));
+    if (posRef.current) {
+      onUpdate?.(posRef.current);
+      onCommit?.(posRef.current);
+    }
+  };
+
+  const handleElementLayoutChange = (e: LayoutChangeEvent) => {
+    // If using injected frame, measurement is handled elsewhere.
+    if (externalFrame != null) return;
+    internalFrameRef.handleLayoutChange(e);
+  };
+
+  return {
+    handlePointerDown,
+    handlePointerMove,
+    handlePointerUp,
+    handleElementLayoutChange,
+  };
+}
+
+type UsePointerAxisReturnValue = UsePointerAxisReturnValueBase<
+  TouchEvent,
+  LayoutChangeEvent
+>;
+
+export { usePointerAxis };
+export type { PointerAxisPosition, UsePointerAxisProps, UsePointerAxisReturnValue };

package/src/shared/hooks/use-pointer-axis/types.ts

@@ -0,0 +1,37 @@
+import type { ElementFrame } from "../use-element-frame/index.js";
+
+/** Pointer position in the element’s local frame. */
+type PointerAxisPosition = {
+  /** Horizontal offset from element's left edge (px). Can be <0 or >length. */
+  offset: number;
+  /** offset / elementLength. Can be <0 or >1. */
+  offsetRatio: number;
+  /** Measured length of the element along this axis (px). */
+  elementLength: number;
+};
+
+/** Interaction callbacks. */
+type UsePointerAxisProps = {
+  axis?: PointerAxis;
+  /** Injected measurement frame */
+  frame?: ElementFrame;
+  /** Fires during drag/move. */
+  onUpdate?: (pos: PointerAxisPosition) => void;
+  /** Fires on pointer up (final value). */
+  onCommit?: (pos: PointerAxisPosition) => void;
+};
+
+type UsePointerAxisReturnValueBase<TPointer, TLayout> = {
+  /** Bind on CONTAINER (or ELEMENT if container === element): <view bindtouchstart|bindmousedown={handlePointerDown} /> */
+  handlePointerDown: (e: TPointer) => void;
+  /** Bind on CONTAINER (or ELEMENT if container === element): <view bindtouchmove|bindmousemove={handlePointerMove} /> */
+  handlePointerMove: (e: TPointer) => void;
+  /** Bind on CONTAINER (or ELEMENT if container===element): <view bindtouchend|bindtouchcancel|bindmousedown|bindmousecancel={handlePointerUp} /> */
+  handlePointerUp: (e: TPointer) => void;
+  /** Bind on ELEMENT: <view bindlayoutchange={handleElementLayoutChange} /> */
+  handleElementLayoutChange: (e: TLayout) => void;
+};
+
+type PointerAxis = "x" | "y";
+
+export type { PointerAxis, PointerAxisPosition, UsePointerAxisProps, UsePointerAxisReturnValueBase };

package/src/shared/hooks/use-pointer-point/index.ts

@@ -0,0 +1,112 @@
+import { useRef, useState } from "@lynx-js/react";
+import { useTouchEmulation } from "@lynx-js/react-use";
+import type { LayoutChangeEvent, MouseEvent, TouchEvent } from "@lynx-js/types";
+import { useElementFrame } from "../use-element-frame/index.js";
+import { usePointerAxis } from "../use-pointer-axis/index.js";
+
+export type PointerPoint = { x: number; y: number };
+
+export type UsePointerPointProps = {
+  x0?: number;
+  y0?: number;
+};
+
+export type PointerBindProps = {
+  /** Pointer (touch/mouse) handlers bound at the field level. */
+  bindtouchstart?: (e: TouchEvent) => void;
+  bindtouchmove?: (e: TouchEvent) => void;
+  bindtouchend?: (e: TouchEvent) => void;
+  bindtouchcancel?: (e: TouchEvent) => void;
+
+  bindmousedown?: (e: MouseEvent) => void;
+  bindmousemove?: (e: MouseEvent) => void;
+  bindmouseup?: (e: MouseEvent) => void;
+
+  /** Layout measurement handler for field coordinate mapping. */
+  bindlayoutchange?: (e: LayoutChangeEvent) => void;
+};
+
+export type UsePointerPointReturnValue = {
+  p: PointerPoint;
+  bind: PointerBindProps;
+  handlePointerDown: (e: TouchEvent) => void;
+  handlePointerMove: (e: TouchEvent) => void;
+  handlePointerUp: (e: TouchEvent) => void;
+  handleElementLayoutChange: (e: LayoutChangeEvent) => void;
+};
+
+function usePointerPoint({
+  x0 = 0.5,
+  y0 = 0.5,
+}: UsePointerPointProps = {}): UsePointerPointReturnValue {
+  const [p, setP] = useState<PointerPoint>({ x: x0, y: y0 });
+
+  const lastXRef = useRef(x0);
+  const lastYRef = useRef(y0);
+
+  const frameRef = useElementFrame();
+
+  const axisX = usePointerAxis({
+    axis: "x",
+    frame: frameRef,
+    onUpdate(pos) {
+      lastXRef.current = pos.offsetRatio;
+      setP({ x: lastXRef.current, y: lastYRef.current });
+    },
+  });
+
+  const axisY = usePointerAxis({
+    axis: "y",
+    frame: frameRef,
+    onUpdate(pos) {
+      lastYRef.current = pos.offsetRatio;
+      setP({ x: lastXRef.current, y: lastYRef.current });
+    },
+  });
+
+  const handlePointerDown = (e: TouchEvent) => {
+    axisY.handlePointerDown(e);
+    axisX.handlePointerDown(e);
+  };
+
+  const handlePointerMove = (e: TouchEvent) => {
+    axisY.handlePointerMove(e);
+    axisX.handlePointerMove(e);
+  };
+
+  const handlePointerUp = (e: TouchEvent) => {
+    axisY.handlePointerUp(e);
+    axisX.handlePointerUp(e);
+  };
+
+  const handleElementLayoutChange = (e: LayoutChangeEvent) => {
+    frameRef.handleLayoutChange(e);
+  };
+
+  // One emulation at the boundary (touch + mouse)
+  const bindPointer = useTouchEmulation({
+    onTouchStart: handlePointerDown,
+    onTouchMove: handlePointerMove,
+    onTouchEnd: handlePointerUp,
+  });
+
+  return {
+    p,
+    handlePointerDown,
+    handlePointerMove,
+    handlePointerUp,
+    handleElementLayoutChange,
+    bind: {
+      bindtouchstart: bindPointer.bindtouchstart,
+      bindtouchmove: bindPointer.bindtouchmove,
+      bindtouchend: bindPointer.bindtouchend,
+      bindtouchcancel: bindPointer.bindtouchcancel,
+      bindmousedown: bindPointer.bindmousedown,
+      bindmousemove: bindPointer.bindmousemove,
+      bindmouseup: bindPointer.bindmouseup,
+      bindlayoutchange: handleElementLayoutChange,
+    },
+  };
+}
+
+export { usePointerPoint };

package/src/shared/hooks/use-pointer-field-point/index.ts

@@ -1,85 +0,0 @@
-import { useRef, useState } from "@lynx-js/react";
-import type { LayoutChangeEvent, TouchEvent } from "@lynx-js/types";
-import { usePointerInteraction } from "../use-pointer-interaction/index.js";
-
-type FieldPoint = {
-  /** Normalized x in [0, 1] (not clamped). */
-  x: number;
-  /** Normalized y in [0, 1] (not clamped). */
-  y: number;
-};
-
-type UsePointerFieldPointProps = {
-  /** Initial normalized x, defaults to 0.5*/
-  x0?: number;
-  y0?: number;
-};
-
-function usePointerFieldPoint({ x0 = 0.5, y0 = 0.5 }: UsePointerFieldPointProps = {}) {
-  const [p, setP] = useState<FieldPoint>({ x: x0, y: y0 });
-
-  const eleTopRef = useRef<number | null>(null);
-  const eleHeightRef = useRef(0);
-
-  const lastYRatioRef = useRef(y0);
-
-  const pointer = usePointerInteraction({
-    onUpdate(pos) {
-      setP({
-        x: pos.offsetRatio,
-        y: lastYRatioRef.current,
-      });
-    },
-  });
-
-  const updateYFromEvent = (e: TouchEvent) => {
-    const top = eleTopRef.current;
-    const height = eleHeightRef.current;
-    if (top != null && height > 0) {
-      lastYRatioRef.current = (e.detail.y - top) / height;
-    }
-  };
-
-  const handlePointerDown2D = (e: TouchEvent) => {
-    updateYFromEvent(e);
-    pointer.handlePointerDown(e);
-  };
-
-  const handlePointerMove2D = (e: TouchEvent) => {
-    updateYFromEvent(e);
-    // X handled by existing hook
-    pointer.handlePointerMove(e);
-  };
-
-  const handleLayoutChange2D = (e: LayoutChangeEvent) => {
-    eleHeightRef.current = e.detail.height;
-
-    const currentTarget = lynx
-      .createSelectorQuery()
-      // @ts-expect-error
-      .selectUniqueID(e.currentTarget.uid);
-
-    currentTarget
-      ?.invoke({
-        method: "boundingClientRect",
-        params: { relativeTo: "screen" },
-        success: (res: { top: number }) => {
-          eleTopRef.current = res.top;
-        },
-      })
-      .exec();
-
-    pointer.handleElementLayoutChange(e);
-  };
-
-  return {
-    p,
-    handlePointerDown: handlePointerDown2D,
-    handlePointerMove: handlePointerMove2D,
-    handlePointerUp: pointer.handlePointerUp,
-    handleElementLayoutChange: handleLayoutChange2D,
-  };
-}
-
-export { usePointerFieldPoint };
-export type { FieldPoint };

package/src/shared/hooks/use-pointer-interaction/index.ts

@@ -1,100 +0,0 @@
-import { useRef } from "@lynx-js/react";
-import type { LayoutChangeEvent, TouchEvent } from "@lynx-js/types";
-import type { PointerPosition, UsePointerInteractionProps, UsePointerInteractionReturnValueBase } from "./types.js";
-
-/**
- * Pointer → element-local coordinates adapter.
- *
- * - The container usually hosts touch/pointer events (recommended for larger hit area).
- * - The element provides the measurement frame (layout + bounding rect).
- * - If you don't need a separate container, you may bind all handlers on the element
- *   itself (container === element).
- *
- * No clamping/step logic is applied here.
- */
-function usePointerInteraction({
-  onUpdate,
-  onCommit,
-}: UsePointerInteractionProps = {}): UsePointerInteractionReturnValue {
-  /** Element (coordinate frame) & metrics */
-  const eleLeftRef = useRef<number | null>(null);
-  const eleWidthRef = useRef(0);
-
-  /** Last computed pointer position snapshot */
-  const posRef = useRef<PointerPosition | null>(null);
-
-  const draggingRef = useRef(false);
-
-  const buildPosition = (x: number): PointerPosition | null => {
-    const width = eleWidthRef.current;
-    const left = eleLeftRef.current;
-
-    if (width > 0 && left != null) {
-      const offset = x - left;
-      const offsetRatio = offset / width;
-      const pos = { offset, offsetRatio, elementWidth: width };
-      posRef.current = pos;
-      return pos;
-    }
-    return null;
-  };
-
-  const handlePointerDown = (e: TouchEvent) => {
-    draggingRef.current = true;
-    buildPosition(e.detail.x);
-    if (posRef.current) {
-      onUpdate?.(posRef.current);
-    }
-  };
-
-  const handlePointerMove = (e: TouchEvent) => {
-    if (!draggingRef.current) return;
-    buildPosition(e.detail.x);
-    if (posRef.current) {
-      onUpdate?.(posRef.current);
-    }
-  };
-
-  const handlePointerUp = (e: TouchEvent) => {
-    draggingRef.current = false;
-    buildPosition(e.detail.x);
-    if (posRef.current) {
-      onUpdate?.(posRef.current);
-      onCommit?.(posRef.current);
-    }
-  };
-
-  const handleElementLayoutChange = (e: LayoutChangeEvent) => {
-    eleWidthRef.current = e.detail.width;
-
-    const currentTarget = lynx
-      .createSelectorQuery()
-      // @ts-expect-error
-      .selectUniqueID(e.currentTarget.uid);
-
-    currentTarget
-      ?.invoke({
-        method: "boundingClientRect",
-        params: { relativeTo: "screen" }, // screen-based so it matches e.detail.x
-        success: (res: { left: number }) => {
-          eleLeftRef.current = res.left;
-        },
-      })
-      .exec();
-  };
-
-  return {
-    handlePointerDown,
-    handlePointerMove,
-    handlePointerUp,
-    handleElementLayoutChange,
-  };
-}
-
-type UsePointerInteractionReturnValue = UsePointerInteractionReturnValueBase<
-  TouchEvent,
-  LayoutChangeEvent
->;
-
-export { usePointerInteraction };
-export type { PointerPosition, UsePointerInteractionProps, UsePointerInteractionReturnValue };

package/src/shared/hooks/use-pointer-interaction/types.ts

@@ -1,30 +0,0 @@
-/** Pointer position in the element’s local frame. */
-interface PointerPosition {
-  /** Horizontal offset from element's left edge (px). Can be <0 or >width. */
-  offset: number;
-  /** offset / elementWidth. Can be <0 or >1. */
-  offsetRatio: number;
-  /** Measured width of the element (px). */
-  elementWidth: number;
-}
-
-/** Interaction callbacks. */
-interface UsePointerInteractionProps {
-  /** Fires during drag/move. */
-  onUpdate?: (pos: PointerPosition) => void;
-  /** Fires on pointer up (final value). */
-  onCommit?: (pos: PointerPosition) => void;
-}
-
-type UsePointerInteractionReturnValueBase<TTouch, TLayout> = {
-  /** Bind on CONTAINER (or ELEMENT if container === element): <view bindtouchstart={handlePointerDown} /> */
-  handlePointerDown: (e: TTouch) => void;
-  /** Bind on CONTAINER (or ELEMENT if container === element): <view bindtouchmove={handlePointerMove} /> */
-  handlePointerMove: (e: TTouch) => void;
-  /** Bind on CONTAINER (or ELEMENT if container===element): <view bindtouchend|bindtouchcancel={handlePointerUp} /> */
-  handlePointerUp: (e: TTouch) => void;
-  /** Bind on ELEMENT: <view bindlayoutchange={handleElementLayoutChange} /> */
-  handleElementLayoutChange: (e: TLayout) => void;
-};
-
-export type { PointerPosition, UsePointerInteractionProps, UsePointerInteractionReturnValueBase };