@lynx-example/design-guide 0.1.1 → 0.3.0

package/src/force_field/index.tsx

@@ -0,0 +1,100 @@
+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 { CELLS } from "./cells.js";
+import { lerpColor } from "./color.js";
+import { makeForceField } from "./field-force.js";
+import { Dot, DotField } from "./field.jsx";
+import { clamp01 } from "./math.js";
+import "./index.css";
+
+const RADIUS = 0.60;
+
+const forceAt = makeForceField({
+  radius: RADIUS,
+  strength: 0.15,
+  falloff: 1.25,
+  mode: "repel",
+  swirl: 0.6,
+  clampMax: 0.14,
+});
+
+function App() {
+  const {
+    p, // Force point in normalized space
+    handlePointerDown,
+    handlePointerMove,
+    handlePointerUp,
+    handleElementLayoutChange,
+  } = usePointerFieldPoint({ x0: 0.6, y0: 1 });
+
+  const models = useMemo(() => {
+    let minD = Infinity;
+    let accentId: string | null = null;
+
+    // First pass: compute everything and track nearest dot
+    const tmp = CELLS.map((cell) => {
+      const f = forceAt({ x: cell.cx, y: cell.cy }, p);
+
+      if (f.d < minD) {
+        minD = f.d;
+        accentId = cell.id;
+      }
+
+      const x = clamp01(cell.cx + f.dx);
+      const y = clamp01(cell.cy + f.dy);
+
+      const dist01 = clamp01(f.d / RADIUS);
+      const g = Math.pow(dist01, 1.5);
+
+      const s = 0.5 + (1 - g) * 2.5;
+      const color = lerpColor(g, "#ff7385", "#00d0f1");
+
+      return { id: cell.id, x, y, s, color };
+    });
+
+    // Second pass: mark accent
+    return tmp.map((m) => ({
+      ...m,
+      useAccent: m.id === accentId,
+    }));
+  }, [p.x, p.y]);
+
+  return (
+    <view className="design-container">
+      <DotField
+        fieldSize={300}
+        dotSize={5}
+        dotAccentColor="#ff1a6e"
+        bindtouchstart={handlePointerDown}
+        bindtouchmove={handlePointerMove}
+        bindtouchend={handlePointerUp}
+        bindlayoutchange={handleElementLayoutChange}
+      >
+        {models.map((m) => (
+          <Dot
+            key={m.id}
+            x={m.x}
+            y={m.y}
+            s={m.s}
+            color={m.color}
+            useAccent={m.useAccent}
+          />
+        ))}
+      </DotField>
+      <Caption
+        title="Force Field"
+        subtitle="Powered by Inline CSS Variables"
+        footnote="Requires Lynx SDK 3.6+"
+      />
+    </view>
+  );
+}
+
+root.render(<App />);
+
+if (import.meta.webpackHot) {
+  import.meta.webpackHot.accept();
+}

package/src/force_field/math.ts

@@ -0,0 +1,8 @@
+export function smoothstep01(x: number) {
+  const t = clamp01(x);
+  return t * t * (3 - 2 * t);
+}
+
+export function clamp01(x: number) {
+  return x < 0 ? 0 : x > 1 ? 1 : x;
+}

package/src/gooey_effect/index.css

@@ -78,29 +78,3 @@
   padding-left: 0;
   padding-right: 0;
 }
-
-.caption-container {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-}
-
-.title {
-  font-size: 16px;
-  font-weight: 600;
-  line-height: 21px;
-  color: #f8f8f8;
-}
-
-.subtitle {
-  line-height: 15px;
-  font-size: 12px;
-  font-weight: 400;
-  color: #b3b3b3;
-}
-
-.footnote {
-  line-height: 14px;
-  font-size: 11px;
-  color: #4f4f4f;
-}

package/src/gooey_effect/index.tsx

@@ -1,5 +1,6 @@
 import { root } from "@lynx-js/react";
 
+import { Caption } from "../shared/components/caption/index.jsx";
 import "./index.css";
 
 function App() {
@@ -13,11 +14,11 @@ function App() {
           <view className="dot g4" />
         </view>
       </view>
-      <view className="caption-container">
-        <text className="title">Gooey Effect</text>
-        <text className="subtitle">Powered by CSS filter: contrast + blur</text>
-        <text className="footnote">Requires Lynx SDK 3.6+</text>
-      </view>
+      <Caption
+        title="Gooey Effect"
+        subtitle="Powered by CSS filter: contrast + blur"
+        footnote="Requires Lynx SDK 3.6+"
+      />
     </view>
   );
 }

package/src/shared/components/caption/index.css

@@ -0,0 +1,27 @@
+.caption-container {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+.caption-title {
+  font-size: 16px;
+  font-weight: 600;
+  line-height: 21px;
+  color: #f8f8f8;
+}
+
+.caption-subtitle {
+  margin-top: 2px;
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 15px;
+  color: #b3b3b3;
+}
+
+.caption-footnote {
+  margin-top: 4px;
+  font-size: 11px;
+  line-height: 14px;
+  color: #4f4f4f;
+}

package/src/shared/components/caption/index.tsx

@@ -0,0 +1,17 @@
+import "./index.css";
+
+type CaptionProps = {
+  title: string;
+  subtitle?: string;
+  footnote?: string;
+};
+
+export function Caption({ title, subtitle, footnote }: CaptionProps) {
+  return (
+    <view className="caption-container">
+      <text className="caption-title">{title}</text>
+      {subtitle && <text className="caption-subtitle">{subtitle}</text>}
+      {footnote && <text className="caption-footnote">{footnote}</text>}
+    </view>
+  );
+}

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

@@ -0,0 +1,85 @@
+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

@@ -0,0 +1,100 @@
+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

@@ -0,0 +1,30 @@
+/** 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 };

package/src/soft_glow/index.css

@@ -0,0 +1,87 @@
+/* Semantic shadow tokens are progressively resolved into
+ * ambient and rim shadows through nested CSS variables,
+ * allowing visual intensity to be adjusted without changing structure.
+ */
+.card {
+  --primary: 254, 105, 161;
+  --secondary: 255, 115, 133;
+  --accent: 169, 152, 191;
+
+  --color: rgba(var(--secondary), 0.65);
+  --rim-color: rgba(var(--primary), 0.9);
+
+  --blur: 3px;
+  --spread: 0;
+  --rim-blur: 2px;
+  --rim-spread: -1px;
+
+  --ambient-shadow: 0 0 var(--blur) var(--spread) var(--color);
+  --rim-shadow: 0 0 var(--rim-blur) var(--rim-spread) var(--rim-color);
+  border-radius: 24px;
+  box-shadow:
+    var(--ambient-shadow),
+    var(--rim-shadow);
+  width: 84px;
+  height: 84px;
+  background: linear-gradient(
+    rgb(var(--accent)),
+    rgb(var(--primary))
+  );
+}
+
+/* Elevation levels adjust shadow parameters
+ * while preserving the same compositional structure.
+ */
+.ele-1 {
+  --blur: 3px;
+  --spread: 0;
+  --rim-blur: 2px;
+  --rim-spread: -1px;
+}
+
+.ele-2 {
+  --blur: 10px;
+  --spread: -1px;
+  --rim-blur: 6px;
+  --rim-spread: -2px;
+}
+
+.ele-3 {
+  --blur: 24px;
+  --spread: -3px;
+  --rim-blur: 12px;
+  --rim-spread: -4px;
+}
+
+.ele-4 {
+  --blur: 44px;
+  --spread: -5px;
+  --rim-blur: 24px;
+  --rim-spread: -8px;
+}
+
+/* =========================
+ * Layout
+ * ========================= */
+
+.design-container {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  background-color: #0d0d0d;
+  gap: 36px;
+  padding: 84px;
+  padding-left: 48px;
+  padding-right: 48px;
+}
+
+.canvas {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  gap: 24px;
+}

package/src/soft_glow/index.tsx

@@ -0,0 +1,31 @@
+import { root } from "@lynx-js/react";
+
+import { Caption } from "../shared/components/caption/index.jsx";
+import "./index.css";
+
+/* Shadow intensity is derived from nested tokens,
+ * resolving into layered ambient and rim shadows.
+ */
+function App() {
+  return (
+    <view className="design-container">
+      <view className="canvas">
+        <view className="card ele-1" />
+        <view className="card ele-2" />
+        <view className="card ele-3" />
+        <view className="card ele-4" />
+      </view>
+      <Caption
+        title="Soft Glow"
+        subtitle="Powered by Nested CSS Variables"
+        footnote="Requires Lynx SDK 3.6+"
+      />
+    </view>
+  );
+}
+
+root.render(<App />);
+
+if (import.meta.webpackHot) {
+  import.meta.webpackHot.accept();
+}