@buoy-gg/shared-ui 7.0.22 → 7.0.24

package/lib/module/ui/backgrounds/primitives.js

@@ -0,0 +1,328 @@
+"use strict";
+
+/**
+ * Drawing + animation primitives for the tool backgrounds.
+ *
+ * HARD CONSTRAINT: Buoy's packages peer-depend on nothing but `react` and
+ * `react-native`. No Skia, no Reanimated, no SVG, no gradient library — a
+ * devtool cannot force a native dependency into someone's app. So every
+ * background here is built out of plain `View`s plus `Animated`, and the
+ * gradients/glows below are *faked* by stacking translucent layers.
+ *
+ * That sounds expensive. It isn't, because of two rules every preset follows:
+ *
+ *  1. **Every animation is native-driven.** `useNativeDriver: true` on a
+ *     looping `Animated.timing` means the whole loop is handed to the UI thread
+ *     once and never touches JS again — no per-frame callback, no re-render, no
+ *     bridge traffic while it runs. A preset animates a handful of *layers*
+ *     (transform on one parent view), never per-particle.
+ *
+ *  2. **Every static layer is rasterized.** `shouldRasterizeIOS` /
+ *     `renderToHardwareTextureAndroid` turn a layer of 40 dots into a single
+ *     cached GPU texture, so sliding it is one composite — the same cost as
+ *     sliding one view. See `RasterLayer`.
+ *
+ * The result: a preset costs a one-time mount of static views and then ~0
+ * JS-thread work per frame. See `packages/shared/src/ui/backgrounds/README.md`.
+ */
+
+import { memo, useEffect, useRef } from "react";
+import { Animated, AppState, Easing, Platform, StyleSheet, View } from "react-native";
+import { absoluteFill } from "../../utils/absoluteFill.js";
+import { withAlpha } from "./rng.js";
+
+// ============================================================================
+// Animation
+// ============================================================================
+
+/**
+ * A native-driven 0→1 loop.
+ *
+ * The returned value is only ever consumed by `interpolate` inside an
+ * `Animated.View` style, so React never re-renders while it runs. The loop is
+ * stopped when the app backgrounds (a background animation is pure battery
+ * burn) and restarted on foreground.
+ */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function useLoop(durationMs, enabled = true) {
+  const value = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    if (!enabled) return;
+    let anim = null;
+    const start = () => {
+      if (anim) return;
+      value.setValue(0);
+      anim = Animated.loop(Animated.timing(value, {
+        toValue: 1,
+        duration: durationMs,
+        easing: Easing.linear,
+        useNativeDriver: true
+      }));
+      anim.start();
+    };
+    const stop = () => {
+      anim?.stop();
+      anim = null;
+      value.setValue(0);
+    };
+    start();
+    const sub = AppState.addEventListener("change", state => {
+      if (state === "active") start();else stop();
+    });
+    return () => {
+      stop();
+      sub.remove();
+    };
+  }, [durationMs, enabled, value]);
+  return value;
+}
+
+/**
+ * A native-driven 0→1→0 breathe, for glows that pulse rather than travel.
+ * Same no-JS-per-frame guarantee as `useLoop`.
+ */
+export function usePulse(durationMs, enabled = true) {
+  const value = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    if (!enabled) return;
+    let anim = null;
+    const start = () => {
+      if (anim) return;
+      value.setValue(0);
+      anim = Animated.loop(Animated.sequence([Animated.timing(value, {
+        toValue: 1,
+        duration: durationMs / 2,
+        easing: Easing.inOut(Easing.quad),
+        useNativeDriver: true
+      }), Animated.timing(value, {
+        toValue: 0,
+        duration: durationMs / 2,
+        easing: Easing.inOut(Easing.quad),
+        useNativeDriver: true
+      })]));
+      anim.start();
+    };
+    const stop = () => {
+      anim?.stop();
+      anim = null;
+    };
+    start();
+    const sub = AppState.addEventListener("change", state => {
+      if (state === "active") start();else stop();
+    });
+    return () => {
+      stop();
+      sub.remove();
+    };
+  }, [durationMs, enabled, value]);
+  return value;
+}
+
+// ============================================================================
+// Layers
+// ============================================================================
+
+/**
+ * A layer whose children are static and should be flattened into one GPU
+ * texture. Wrap anything that gets translated/scaled as a whole — this is what
+ * makes a 40-dot star band cost the same to move as a single view.
+ */
+export const RasterLayer = /*#__PURE__*/memo(function RasterLayer({
+  style,
+  raster = true,
+  children
+}) {
+  return /*#__PURE__*/_jsx(View, {
+    style: style,
+    pointerEvents: "none"
+    // Both are no-ops on the platform they don't belong to, and on web
+    // (react-native-web) neither exists — there the browser already
+    // composites a transformed subtree on the GPU.
+    ,
+    shouldRasterizeIOS: raster && Platform.OS === "ios",
+    renderToHardwareTextureAndroid: raster && Platform.OS === "android",
+    children: children
+  });
+});
+
+/**
+ * Fake radial gradient: concentric rounded views, each a constant per-ring
+ * alpha, with radii shrinking on a curve. Alpha compositing of N equal layers
+ * gives `1 - (1-a)^N` at the centre, so `a` is solved from the requested peak
+ * alpha and the falloff comes from the radius curve.
+ *
+ * 8 rings is the sweet spot on a dark surface — below that you can see banding,
+ * above it you're paying for views nobody can distinguish.
+ */
+export const RadialGlow = /*#__PURE__*/memo(function RadialGlow({
+  size,
+  color,
+  alpha = 0.35,
+  rings = 8,
+  falloff = 1.7,
+  style
+}) {
+  const per = 1 - Math.pow(1 - alpha, 1 / rings);
+  const layers = [];
+  for (let i = 0; i < rings; i++) {
+    const d = size * Math.pow((rings - i) / rings, falloff);
+    layers.push(/*#__PURE__*/_jsx(View, {
+      style: {
+        position: "absolute",
+        left: (size - d) / 2,
+        top: (size - d) / 2,
+        width: d,
+        height: d,
+        borderRadius: d / 2,
+        backgroundColor: withAlpha(color, per)
+      }
+    }, i));
+  }
+  return /*#__PURE__*/_jsx(View, {
+    style: [{
+      width: size,
+      height: size
+    }, style],
+    pointerEvents: "none",
+    shouldRasterizeIOS: Platform.OS === "ios",
+    renderToHardwareTextureAndroid: Platform.OS === "android",
+    children: layers
+  });
+});
+
+/**
+ * Fake linear gradient: `bands` stacked strips with linearly interpolated
+ * alpha. Used for scrims (keep text readable over a busy field) and for
+ * horizon glows. 12–16 bands is invisible as banding at these alphas.
+ */
+export const LinearFade = /*#__PURE__*/memo(function LinearFade({
+  color,
+  from = 0,
+  to = 1,
+  bands = 14,
+  direction = "down",
+  style
+}) {
+  const vertical = direction === "down" || direction === "up";
+  const reversed = direction === "up" || direction === "left";
+  const pct = 100 / bands;
+  const strips = [];
+  for (let i = 0; i < bands; i++) {
+    const t = (i + 0.5) / bands;
+    const a = from + (to - from) * (reversed ? 1 - t : t);
+    strips.push(/*#__PURE__*/_jsx(View, {
+      style: vertical ? {
+        position: "absolute",
+        left: 0,
+        right: 0,
+        top: `${i * pct}%`,
+        height: `${pct + 1.2}%`,
+        backgroundColor: withAlpha(color, a)
+      } : {
+        position: "absolute",
+        top: 0,
+        bottom: 0,
+        left: `${i * pct}%`,
+        width: `${pct + 1.2}%`,
+        backgroundColor: withAlpha(color, a)
+      }
+    }, i));
+  }
+  return /*#__PURE__*/_jsx(View, {
+    style: [absoluteFill, style],
+    pointerEvents: "none",
+    children: strips
+  });
+});
+
+/**
+ * Edge darkening. Four `LinearFade`s rather than a real radial vignette —
+ * cheaper, and at these alphas the corners read as round anyway.
+ */
+export const Vignette = /*#__PURE__*/memo(function Vignette({
+  color = "#000000",
+  alpha = 0.55,
+  spread = 0.34
+}) {
+  // Each fade fills its own positioned band, rather than trying to unset
+  // `absoluteFill`'s edges through the style array.
+  const band = `${spread * 100}%`;
+  return /*#__PURE__*/_jsxs(View, {
+    style: absoluteFill,
+    pointerEvents: "none",
+    children: [/*#__PURE__*/_jsx(View, {
+      style: {
+        position: "absolute",
+        left: 0,
+        right: 0,
+        top: 0,
+        height: band
+      },
+      children: /*#__PURE__*/_jsx(LinearFade, {
+        color: color,
+        from: alpha,
+        to: 0,
+        direction: "down",
+        bands: 10
+      })
+    }), /*#__PURE__*/_jsx(View, {
+      style: {
+        position: "absolute",
+        left: 0,
+        right: 0,
+        bottom: 0,
+        height: band
+      },
+      children: /*#__PURE__*/_jsx(LinearFade, {
+        color: color,
+        from: 0,
+        to: alpha,
+        direction: "down",
+        bands: 10
+      })
+    }), /*#__PURE__*/_jsx(View, {
+      style: {
+        position: "absolute",
+        top: 0,
+        bottom: 0,
+        left: 0,
+        width: band
+      },
+      children: /*#__PURE__*/_jsx(LinearFade, {
+        color: color,
+        from: alpha,
+        to: 0,
+        direction: "right",
+        bands: 8
+      })
+    }), /*#__PURE__*/_jsx(View, {
+      style: {
+        position: "absolute",
+        top: 0,
+        bottom: 0,
+        right: 0,
+        width: band
+      },
+      children: /*#__PURE__*/_jsx(LinearFade, {
+        color: color,
+        from: 0,
+        to: alpha,
+        direction: "right",
+        bands: 8
+      })
+    })]
+  });
+});
+
+/** Flat wash used as the base coat under every preset. */
+export const Base = /*#__PURE__*/memo(function Base({
+  color
+}) {
+  return /*#__PURE__*/_jsx(View, {
+    style: [absoluteFill, {
+      backgroundColor: color
+    }],
+    pointerEvents: "none"
+  });
+});
+export const hairline = StyleSheet.hairlineWidth;

package/lib/module/ui/backgrounds/registry.js

@@ -0,0 +1,105 @@
+"use strict";
+
+/**
+ * The catalogue. Adding a preset means adding one entry here — the switcher,
+ * the persisted selection and every tool surface read from this list.
+ *
+ * `nodes` and `views` are not decoration: they are the number of native
+ * animated nodes the preset runs and the rough count of static views it mounts,
+ * so the switcher can show what each look costs while you compare them. Keep
+ * them honest.
+ */
+
+import { Crosshatch, Halftone, HexMesh, Instrument, IsoGrid, PerfBoard, Radar, Waffle } from "./variants/lattice.js";
+import { DeepField } from "./variants/deepField.js";
+import { Starfield } from "./variants/starfield.js";
+export const BACKGROUND_PRESETS = [{
+  id: "off",
+  label: "Off",
+  blurb: "Plain black — the baseline to compare against",
+  nodes: 0,
+  views: 1,
+  Component: null
+}, {
+  id: "starfield",
+  label: "Starfield",
+  blurb: "Five depth bands drifting at parallax speeds",
+  nodes: 6,
+  views: 222,
+  Component: Starfield
+}, {
+  id: "deepfield",
+  label: "Deep Field",
+  blurb: "The Everlights field, 1:1 — 160 stars, richer but pricier",
+  nodes: 22,
+  views: 462,
+  Component: DeepField
+}, {
+  id: "hexmesh",
+  label: "Hex Mesh",
+  blurb: "Diamond lattice with a slow breath",
+  nodes: 1,
+  views: 160,
+  Component: HexMesh
+}, {
+  id: "isogrid",
+  label: "Iso Grid",
+  blurb: "Three-axis isometric ruling",
+  nodes: 1,
+  views: 66,
+  Component: IsoGrid
+}, {
+  id: "crosshatch",
+  label: "Crosshatch",
+  blurb: "Fine 45° weave, drafting-paper quiet",
+  nodes: 1,
+  views: 64,
+  Component: Crosshatch
+}, {
+  id: "perfboard",
+  label: "Perf Board",
+  blurb: "Solder-pad matrix with datum pads every fourth",
+  nodes: 1,
+  views: 150,
+  Component: PerfBoard
+}, {
+  id: "halftone",
+  label: "Halftone",
+  blurb: "Dot grid swelling toward the light",
+  nodes: 1,
+  views: 176,
+  Component: Halftone
+}, {
+  id: "waffle",
+  label: "Waffle",
+  blurb: "Machined panel of rounded cells",
+  nodes: 1,
+  views: 88,
+  Component: Waffle
+}, {
+  id: "instrument",
+  label: "Instrument",
+  blurb: "Ruled scales with major graduations",
+  nodes: 1,
+  views: 110,
+  Component: Instrument
+}, {
+  id: "radar",
+  label: "Radar",
+  blurb: "Rings and spokes under a rotating sweep",
+  nodes: 2,
+  views: 40,
+  Component: Radar
+}];
+export const DEFAULT_BACKGROUND = "hexmesh";
+export function presetIndex(id) {
+  const i = BACKGROUND_PRESETS.findIndex(p => p.id === id);
+  return i < 0 ? 0 : i;
+}
+export function presetAt(index) {
+  const n = BACKGROUND_PRESETS.length;
+  return BACKGROUND_PRESETS[(index % n + n) % n];
+}
+export function getPreset(id) {
+  return BACKGROUND_PRESETS[presetIndex(id)];
+}

package/lib/module/ui/backgrounds/rng.js

@@ -0,0 +1,65 @@
+"use strict";
+
+/**
+ * Deterministic scatter tables for the tool backgrounds.
+ *
+ * Every preset needs a pile of "random" positions, sizes and phases. Those are
+ * generated ONCE at module load from a fixed seed and frozen, so:
+ *   - the same seed always paints the same field (screenshots are stable, and
+ *     two tools showing the same background look identical),
+ *   - no allocation happens on mount or on any re-render — the presets only
+ *     read these arrays.
+ *
+ * Ported from the seeded field in the Everlights starfield (mulberry32).
+ */
+
+export function mulberry32(seed) {
+  return () => {
+    seed = seed + 0x6d2b79f5 | 0;
+    let t = Math.imul(seed ^ seed >>> 15, 1 | seed);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+
+/** `count` numbers in [0,1) from `seed`. */
+export function scatter(seed, count) {
+  const rnd = mulberry32(seed >>> 0);
+  const out = new Array(count);
+  for (let i = 0; i < count; i++) out[i] = rnd();
+  return out;
+}
+
+/** `#RRGGBB` (or `#RGB`) + alpha 0..1 → `rgba(...)`. */
+export function withAlpha(hex, alpha) {
+  let h = hex.replace("#", "");
+  if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+  const n = parseInt(h, 16);
+  const r = n >> 16 & 255;
+  const g = n >> 8 & 255;
+  const b = n & 255;
+  const a = alpha < 0 ? 0 : alpha > 1 ? 1 : alpha;
+  return `rgba(${r},${g},${b},${a.toFixed(3)})`;
+}
+
+/**
+ * `hex` at `alpha` composited over an opaque `base`, returned as an OPAQUE
+ * colour.
+ *
+ * Over a known backdrop this is pixel-identical to drawing the translucent
+ * colour — the GPU just doesn't have to blend it. Only valid where nothing
+ * else sits between the layer and `base`.
+ */
+export function flattenOver(hex, alpha, base) {
+  const parse = h => {
+    let v = h.replace("#", "");
+    if (v.length === 3) v = v[0] + v[0] + v[1] + v[1] + v[2] + v[2];
+    const n = parseInt(v, 16);
+    return [n >> 16 & 255, n >> 8 & 255, n & 255];
+  };
+  const [r, g, b] = parse(hex);
+  const [br, bg, bb] = parse(base);
+  const a = alpha < 0 ? 0 : alpha > 1 ? 1 : alpha;
+  const mix = (c, bc) => Math.round(c * a + bc * (1 - a));
+  return `rgb(${mix(r, br)},${mix(g, bg)},${mix(b, bb)})`;
+}

package/lib/module/ui/backgrounds/types.js

@@ -0,0 +1 @@
+"use strict";