@lynx-example/design-guide 0.1.0 → 0.2.0

package/src/force_field/cells.ts

@@ -0,0 +1,20 @@
+type Cell = { id: string; i: number; j: number; cx: number; cy: number };
+
+const cols = 20;
+const rows = 20;
+const CELLS: Cell[] = [];
+
+for (let c = 0; c < cols; c++) {
+  for (let r = 0; r < rows; r++) {
+    CELLS.push({
+      id: `${r}-${c}`,
+      i: r,
+      j: c,
+      // normalized cell center in [0,1]
+      cx: (c + 0.5) / cols,
+      cy: (r + 0.5) / rows,
+    });
+  }
+}
+
+export { CELLS };

package/src/force_field/color.ts

@@ -0,0 +1,58 @@
+import { clamp01 } from "./math.js";
+
+function lerpColor(
+  t: number,
+  colorA: string,
+  colorB: string,
+): string {
+  const [rA, gA, bA] = hexToRgb(colorA);
+  const [rB, gB, bB] = hexToRgb(colorB);
+
+  const r = mix(rA, rB, t);
+  const g = mix(gA, gB, t);
+  const b = mix(bA, bB, t);
+
+  return rgbToHex(r, g, b);
+}
+
+function hexToRgb(hex: string): [number, number, number] {
+  const n = hex.replace("#", "");
+  return [
+    parseInt(n.slice(0, 2), 16),
+    parseInt(n.slice(2, 4), 16),
+    parseInt(n.slice(4, 6), 16),
+  ];
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  return (
+    "#"
+    + [r, g, b]
+      .map(v => Math.round(v).toString(16).padStart(2, "0"))
+      .join("")
+  );
+}
+
+function mix(a: number, b: number, t: number) {
+  return a * (1 - t) + b * t;
+}
+
+function lerpColor4(
+  t: number,
+  c0: string,
+  c1: string,
+  c2: string,
+  c3: string,
+): string {
+  const x = clamp01(t);
+
+  if (x < 1 / 3) {
+    return lerpColor(x / (1 / 3), c0, c1);
+  }
+  if (x < 2 / 3) {
+    return lerpColor((x - 1 / 3) / (1 / 3), c1, c2);
+  }
+  return lerpColor((x - 2 / 3) / (1 / 3), c2, c3);
+}
+
+export { lerpColor, lerpColor4 };

package/src/force_field/field-force.ts

@@ -0,0 +1,97 @@
+import { smoothstep01 } from "./math.js";
+export type Vec2 = { x: number; y: number };
+
+export type ForceFieldOptions = {
+  // Core shape
+  /**
+   * influence radius in normalized space (0..sqrt(2))
+   */
+  radius?: number;
+  /**
+   *  overall displacement magnitude (normalized units)
+   */
+  strength?: number;
+  /**
+   * higher = faster decay
+   */
+  falloff?: number;
+  mode?: "repel" | "attract";
+
+  // Optional style
+  /**
+   * tangential component, gives "vortex" feel
+   */
+  swirl?: number;
+  /**
+   * avoids singularity near center
+   */
+  soften?: number;
+  /**
+   *  max displacement magnitude
+   */
+  clampMax?: number;
+};
+
+const DEFAULTS: Required<ForceFieldOptions> = {
+  radius: 0.45,
+  strength: 0.085,
+  falloff: 2.2,
+  mode: "repel",
+  swirl: 0.0,
+  soften: 0.02,
+  clampMax: 0.12,
+};
+
+export function makeForceField(user: ForceFieldOptions = {}) {
+  const opt = { ...DEFAULTS, ...user };
+
+  return function forceAt(cell: Vec2, p: Vec2) {
+    // Vector from p -> cell
+    const vx = cell.x - p.x;
+    const vy = cell.y - p.y;
+    const d = Math.sqrt(vx * vx + vy * vy);
+
+    // Outside radius: no force
+    if (d >= opt.radius) return { dx: 0, dy: 0, t: 1, d };
+
+    // Normalize direction (avoid NaN at center)
+    const inv = 1 / Math.max(d, opt.soften);
+    const nx = vx * inv;
+    const ny = vy * inv;
+
+    // 0..1 influence inside radius (1 at center, 0 at edge)
+    const u = 1 - d / opt.radius;
+
+    // Smooth & decay
+    const influence = smoothstep01(u);
+    const decay = Math.pow(influence, opt.falloff);
+
+    // Base radial magnitude
+    let mag = opt.strength * decay;
+
+    // Repel vs attract
+    if (opt.mode === "attract") mag = -mag;
+
+    // Add optional swirl (tangential)
+    // Tangent is perpendicular to radial: ( -ny, nx )
+    const tx = -ny;
+    const ty = nx;
+
+    let dx = nx * mag + tx * (opt.swirl * mag);
+    let dy = ny * mag + ty * (opt.swirl * mag);
+
+    // Clamp displacement magnitude for stability
+    const m = Math.sqrt(dx * dx + dy * dy);
+    if (m > opt.clampMax) {
+      const s = opt.clampMax / m;
+      dx *= s;
+      dy *= s;
+    }
+
+    // t: a handy 0..1 "field value" you can reuse for color/size
+    // Here we invert so t=0 near center, t=1 far away.
+    const t = 1 - decay;
+
+    return { dx, dy, t, d };
+  };
+}

package/src/force_field/field.css

@@ -0,0 +1,23 @@
+.dot-field {
+  position: relative;
+  --dot-size: 5px;
+  --dot-color: #f8f8f8;
+  --dot-accent-color: #ffff00;
+  --field-size: 300px;
+  width: var(--field-size);
+  height: var(--field-size);
+}
+
+.dot {
+  width: calc(var(--dot-size) * var(--s, 1));
+  height: calc(var(--dot-size) * var(--s, 1));
+  transform: translate(
+    calc(var(--field-size) * var(--x, 0)),
+    calc(var(--field-size) * var(--y, 0))
+  );
+  background-color: var(--dot-color, #f8f8f8);
+  border-radius: 9999px;
+  position: absolute;
+  top: 0;
+  left: 0;
+}

package/src/force_field/field.tsx

@@ -0,0 +1,55 @@
+import type { DotFieldProps, DotProps } from "./field.types.js";
+
+import "./field.css";
+
+/**
+ * Dot consumes normalized, unitless styling parameters.
+ * Concrete layout and sizing are resolved against field-level
+ * CSS variables, rather than computed imperatively in JS.
+ */
+function Dot({ x = 0, y = 0, s = 1, color, useAccent }: DotProps) {
+  return (
+    <view
+      className="dot"
+      // Inline CSS var reference: route to a field-scoped CSS token (`--dot-accent-color`)
+      // instead of resolving the color imperatively in JS.
+      style={`--x:${x}; --y:${y}; --s:${s}; background-color:${useAccent ? "var(--dot-accent-color)" : color}`}
+    />
+  );
+}
+
+/**
+ * DotField defines the styling boundary for a dot-based field.
+ * It provides a scoped coordinate system and field-level design tokens
+ * (e.g. --field-size, --dot-size) via CSS variables.
+ */
+function DotField({
+  fieldSize = 200,
+  dotSize = 5,
+  dotColor = "#f8f8f8",
+  dotAccentColor = "#ffff00",
+  children,
+  bindtouchstart,
+  bindtouchmove,
+  bindtouchend,
+  bindtouchcancel,
+  bindlayoutchange,
+}: DotFieldProps) {
+  return (
+    <view
+      /* Styling boundary: inject field-level CSS tokens */
+      style={`--field-size:${fieldSize}px; --dot-size:${dotSize}px; --dot-color:${dotColor}; --dot-accent-color:${dotAccentColor} `}
+      className="dot-field"
+      /* Interaction */
+      bindtouchstart={bindtouchstart}
+      bindtouchmove={bindtouchmove}
+      bindtouchend={bindtouchend}
+      bindtouchcancel={bindtouchcancel}
+      bindlayoutchange={bindlayoutchange}
+    >
+      {children}
+    </view>
+  );
+}
+
+export { Dot, DotField };

package/src/force_field/field.types.ts

@@ -0,0 +1,50 @@
+import type { ReactNode } from "@lynx-js/react";
+import type { LayoutChangeEvent, TouchEvent } from "@lynx-js/types";
+
+type DotProps = {
+  /** Normalized x position in the field (0..1). */
+  x?: number;
+
+  /** Normalized y position in the field (0..1). */
+  y?: number;
+
+  /** Relative scale factor, resolved against `--dot-size`. Defaults to 1. */
+  s?: number;
+
+  /** Optional explicit color for this dot. */
+  color?: string;
+
+  /** Use the field-level accent color (`--dot-accent-color`). */
+  useAccent?: boolean;
+};
+
+type DotFieldProps = {
+  /** Field size in pixels (defines the coordinate space). */
+  fieldSize?: number;
+
+  /** Base dot size in pixels. */
+  dotSize?: number;
+
+  /** Default dot color (`--dot-color`). */
+  dotColor?: string;
+
+  /** Accent dot color (`--dot-accent-color`). */
+  dotAccentColor?: string;
+
+  /** Extra inline CSS applied at the field boundary. */
+  style?: string;
+
+  /** Field children (dots or other field-aware elements). */
+  children?: ReactNode;
+
+  /** Pointer / touch handlers bound at the field level. */
+  bindtouchstart?: (e: TouchEvent) => void;
+  bindtouchmove?: (e: TouchEvent) => void;
+  bindtouchend?: (e: TouchEvent) => void;
+  bindtouchcancel?: (e: TouchEvent) => void;
+
+  /** Layout measurement handler for field coordinate mapping. */
+  bindlayoutchange?: (e: LayoutChangeEvent) => void;
+};
+
+export type { DotFieldProps, DotProps };

package/src/force_field/index.css

@@ -0,0 +1,17 @@
+/* =========================
+ * Layout
+ * ========================= */
+
+.design-container {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  background-color: #0d0d0d;
+  gap: 24px;
+  padding: 84px;
+  padding-left: 48px;
+  padding-right: 48px;
+}

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 { lerpColor4 } 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.14,
+  falloff: 1.8,
+  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.25);
+
+      const s = 0.6 + (1 - g) * 1.8;
+      const color = lerpColor4(g, "#EBF4F6", "#7AB2B2", "#088395", "#09637E");
+
+      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="#ff7385"
+        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

@@ -1,34 +1,22 @@
-.container {
-  width: 100%;
-  height: 100%;
-  display: flex;
-  flex-direction: column;
-  justify-content: center;
-  align-items: center;
-  background-color: black;
-
-  gap: 48px;
-}
-
 .stage {
-  width: 100%;
-  height: 200px;
   filter: contrast(100);
-
   /* background color must be explicit, for contrast */
   background-color: black;
+
+  width: 100%;
+  height: 200px;
 }
 
 .inner-stage {
+  /* Lynx: only one filter function per declaration */
+  filter: blur(20px);
+
   width: 100%;
   height: 100%;
   display: flex;
   justify-content: center;
   align-items: center;
   gap: 4px;
-
-  /* Lynx: only one filter function per declaration */
-  filter: blur(20px);
 }
 
 .dot {
@@ -72,28 +60,21 @@
   }
 }
 
-.caption-container {
+/* =========================
+ * Layout
+ * ========================= */
+
+.design-container {
+  min-width: 300px;
+  width: 100%;
+  height: 100%;
   display: flex;
   flex-direction: column;
+  justify-content: center;
   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;
-}
+  background-color: black;
+  gap: 48px;
 
-.footnote {
-  line-height: 14px;
-  font-size: 11px;
-  color: #4f4f4f;
+  padding-left: 0;
+  padding-right: 0;
 }

package/src/gooey_effect/index.tsx

@@ -1,10 +1,11 @@
 import { root } from "@lynx-js/react";
 
+import { Caption } from "../shared/components/caption/index.jsx";
 import "./index.css";
 
 function App() {
   return (
-    <view className="container">
+    <view className="design-container">
       <view className="stage">
         <view className="inner-stage">
           <view className="dot g1" />
@@ -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 };