@robr0/design-system 0.5.0 → 0.7.0

package/components/ShaderField/ShaderField.js

@@ -0,0 +1,54 @@
+import { jsx } from "react/jsx-runtime";
+import React, { useRef, useMemo, useState, useEffect } from "react";
+import { DEFAULT_SHADER_BLOBS, DEFAULT_SHADER_PARAMS, useShaderField } from "./useShaderField.js";
+import "./ShaderField.css";
+const WATCHDOG_MS = 1500;
+const ShaderField = React.forwardRef(
+  ({
+    params,
+    blobs = DEFAULT_SHADER_BLOBS,
+    enabled = true,
+    onStatusChange,
+    className = "",
+    ...rest
+  }, ref) => {
+    const canvasRef = useRef(null);
+    React.useImperativeHandle(ref, () => canvasRef.current);
+    const fieldParams = useMemo(
+      () => ({ ...DEFAULT_SHADER_PARAMS, ...params, blobs }),
+      [params, blobs]
+    );
+    const { supported, active } = useShaderField(canvasRef, fieldParams, enabled);
+    const [gaveUp, setGaveUp] = useState(false);
+    useEffect(() => {
+      if (!enabled || active || !supported) return;
+      const timer = window.setTimeout(() => setGaveUp(true), WATCHDOG_MS);
+      return () => window.clearTimeout(timer);
+    }, [enabled, active, supported]);
+    const status = !enabled || !supported ? "unavailable" : active ? "active" : gaveUp ? "unavailable" : "pending";
+    const notify = useRef(onStatusChange);
+    notify.current = onStatusChange;
+    useEffect(() => {
+      notify.current?.(status);
+    }, [status]);
+    if (!enabled) return null;
+    const classes = ["ds-shader-field", className].filter(Boolean).join(" ");
+    return /* @__PURE__ */ jsx(
+      "canvas",
+      {
+        ...rest,
+        ref: canvasRef,
+        className: classes,
+        "data-status": status,
+        "aria-hidden": "true"
+      }
+    );
+  }
+);
+ShaderField.displayName = "ShaderField";
+export {
+  DEFAULT_SHADER_BLOBS,
+  DEFAULT_SHADER_PARAMS,
+  ShaderField,
+  useShaderField
+};

package/components/ShaderField/field.glsl.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GLSL sources for ShaderField, the system's ambient background field.
+ *
+ * This file owns the shader and BLOB_COUNT only. The blob table and every
+ * tuneable parameter are data, passed in by the caller, so a look can be
+ * retuned without touching GLSL.
+ *
+ * The field is a sum of soft Gaussian sources. It computes the true Gaussian
+ * falloff a stack of blurred CSS discs only approximates, blends in linear
+ * space so midpoints keep their saturation, warps the field with fbm noise so
+ * it flows instead of translating rigidly, and dithers away the 8-bit banding
+ * these wide, soft ramps otherwise produce.
+ *
+ * Coordinate space is chosen to match a CSS blob layer exactly, so a fallback
+ * built from absolutely-positioned discs lines up with it: origin at the
+ * container centre (`left`/`top: 50%`), one unit = container width (discs are
+ * vw-sized, and CSS percentage margins — top included — resolve against the
+ * containing block's width). Centres are therefore constants that never need
+ * re-uploading on resize.
+ *
+ * Colours arrive already converted to linear RGB (the hook does the sRGB
+ * decode once per theme change); the shader only encodes back at the end.
+ */
+/**
+ * Sizes the shader's uniform arrays, so it is a compile-time constant here
+ * rather than a length read from data. A caller may pass fewer blobs — unused
+ * slots are parked off-field — but never more; ShaderField's own default table
+ * fills it exactly, and scripts/validate-shader-background.mjs reads this
+ * number out of this file to hold the website's config to it.
+ */
+export declare const BLOB_COUNT = 8;
+export declare const vertexSource = "#version 300 es\n// Fullscreen triangle \u2014 no buffers, three vertices from gl_VertexID.\nvoid main() {\n  vec2 p = vec2((gl_VertexID << 1) & 2, gl_VertexID & 2);\n  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);\n}\n";
+export declare const fragmentSource = "#version 300 es\nprecision highp float;\n\nuniform vec2  u_resolution;  // drawing-buffer size in pixels\nuniform float u_time;        // field time, seconds (speed applied JS-side)\nuniform vec3  u_color[8];  // linear RGB per blob\nuniform vec4  u_blob[8];   // xy = centre, z = sigma, w = emission weight\nuniform vec4  u_motion[8]; // xy = angular speeds, zw = phases\nuniform float u_intensity;   // peak-alpha ceiling\nuniform float u_warp;        // domain-warp strength\nuniform float u_scale;       // noise frequency\nuniform float u_grain;       // film-grain strength\nuniform float u_streak;      // anisotropic stretch: 0 = blobs, 1 = light streams\nuniform vec2  u_mouse;       // pointer in field coordinates (smoothed JS-side)\nuniform float u_mvel;        // smoothed pointer speed, width units/s\nuniform float u_react;       // cursor-reactivity strength\n\nout vec4 outColor;\n\n// Integer hash \u2014 WebGL2 has real uint ops, so no fract(sin()) precision\n// lottery on mobile GPUs.\nuint ihash(uvec2 p) {\n  p = p * uvec2(73333u, 7777u) ^ (p.yx >> 3u);\n  uint h = p.x ^ (p.y * 2654435761u);\n  h ^= h >> 15u;\n  h *= 2246822519u;\n  h ^= h >> 13u;\n  return h;\n}\n\nfloat rnd(ivec2 p) {\n  return float(ihash(uvec2(p)) >> 8) * (1.0 / 16777216.0);\n}\n\nfloat vnoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);\n  ivec2 c = ivec2(i);\n  return mix(\n    mix(rnd(c), rnd(c + ivec2(1, 0)), u.x),\n    mix(rnd(c + ivec2(0, 1)), rnd(c + ivec2(1, 1)), u.x),\n    u.y\n  );\n}\n\n// 3 octaves; a 4th is invisible at this softness.\nfloat fbm(vec2 p) {\n  float s = 0.0;\n  float a = 0.5;\n  for (int i = 0; i < 3; i++) {\n    s += a * vnoise(p);\n    p = p * 2.02 + vec2(17.0, 9.0);\n    a *= 0.5;\n  }\n  return s;\n}\n\nvoid main() {\n  // CSS coordinate space: origin at container centre, one unit = width,\n  // y running downward.\n  vec2 p = (gl_FragCoord.xy - 0.5 * u_resolution) / u_resolution.x;\n  p.y = -p.y;\n\n  // Light-stream axis: a fixed diagonal. Distances across the axis are\n  // magnified before the Gaussian, so every source stretches along it and\n  // the field reads as rays instead of discs.\n  float ca = cos(0.5);\n  float sa = sin(0.5);\n  mat2 toStreak = mat2(ca, -sa, sa, ca);\n  float squeeze = 1.0 + u_streak * 4.0;\n\n  // Domain warp: the field flows rather than drifts. The noise is sampled\n  // in the same anisotropic space, so the flow lines follow the streams.\n  float t = u_time;\n  vec2 ps = toStreak * p;\n  ps.y *= squeeze;\n  vec2 q = vec2(\n    fbm(ps * u_scale + vec2(0.0, t * 0.030)),\n    fbm(ps * u_scale + vec2(5.2, 1.3) - t * 0.024)\n  );\n  vec2 w = p + u_warp * (q - 0.5);\n\n  // Cursor wake: a smooth vortex around the pointer, amplified by speed.\n  // The displacement is built from the *unnormalised* offset so it falls to\n  // zero at the cursor itself. Normalising here (md/mr) made the direction\n  // spin through 360 degrees at full strength across the centre pixel, which\n  // rendered as a pinch \u2014 a cone converging to a point.\n  vec2 md = p - u_mouse;\n  float mr2 = dot(md, md);\n  float minf = exp(-mr2 / (2.0 * 0.22 * 0.22));\n  vec2 swirl = vec2(-md.y, md.x);\n  // smoothstep, not min(): a hard clamp stepped visibly as speed crossed it.\n  float stir = 0.25 + 1.3 * smoothstep(0.0, 0.8, u_mvel);\n  w += u_react * minf * stir * (swirl * 0.9 + md * 0.35);\n\n  // Accumulate true Gaussians in linear space. Positive weights emit;\n  // negative weights absorb (shadows \u2014 the eclipse disc).\n  vec3 acc = vec3(0.0);\n  float cov = 0.0;\n  float shade = 0.0;\n  for (int i = 0; i < 8; i++) {\n    vec2 c = u_blob[i].xy + 0.045 * vec2(\n      cos(u_motion[i].x * t + u_motion[i].z),\n      sin(u_motion[i].y * t + u_motion[i].w)\n    );\n    vec2 d = toStreak * (w - c);\n    d.y *= squeeze;\n    float s = u_blob[i].z;\n    float g = exp(-dot(d, d) / (2.0 * s * s));\n    float wgt = u_blob[i].w;\n    if (wgt >= 0.0) {\n      acc += u_color[i] * (g * wgt);\n      cov += g * wgt;\n    } else {\n      shade += g * -wgt;\n    }\n  }\n\n  // Glow trail: wider and softer than the swirl, and mostly velocity-driven,\n  // so a resting cursor does not park a bright dot on the field.\n  //\n  // The wake brightens whatever colour it is passing over rather than adding\n  // one of its own. Injecting u_color[0] meant the trail always wore the\n  // first blob's token \u2014 gold in the site palette, violet in beam \u2014 which\n  // read as a stray colour with no relationship to the field beneath it.\n  // Weighting by the local hue keeps the wake colour-neutral: it reads as\n  // light falling on the field, and it stays correct for any palette.\n  vec3 local = acc / max(cov, 1e-4);\n  float gfall = exp(-mr2 / (2.0 * 0.3 * 0.3));\n  float glow = u_react * gfall * (0.12 + 0.5 * smoothstep(0.0, 0.8, u_mvel));\n  acc += local * glow;\n  cov += glow;\n\n  vec3 lin = acc / max(cov, 1e-4);\n  float lit = max(cov - shade, 0.0);\n  float alpha = u_intensity * (1.0 - exp(-lit * 0.9));\n\n  vec3 srgb = pow(max(lin, vec3(0.0)), vec3(1.0 / 2.2));\n\n  // Film grain: animated hash noise. At u_grain 0 this degenerates to the\n  // \u00B11/255 dither that kills banding, so the two share one lookup.\n  uvec2 gp = uvec2(gl_FragCoord.xy) + uvec2(\n    uint(fract(t * 7.31) * 1024.0) * 7919u,\n    uint(fract(t * 3.17) * 1024.0) * 104729u\n  );\n  float gr = float(ihash(gp) & 255u) / 255.0 - 0.5;\n  srgb += gr * (1.0 / 255.0 + u_grain * 0.35);\n  // A small grain-driven alpha floor lets the sparkle read even where the\n  // field itself is empty (the reference's grainy dark scene).\n  float grainFloor = u_grain * 0.1 * (gr + 0.5);\n  alpha = clamp(alpha * (1.0 + gr * u_grain * 0.5) + grainFloor, 0.0, 1.0);\n  srgb = clamp(srgb, 0.0, 1.0);\n\n  // Premultiplied output (context is created with premultipliedAlpha: true).\n  outColor = vec4(srgb * alpha, alpha);\n}\n";

package/components/ShaderField/field.glsl.js

@@ -0,0 +1,177 @@
+const BLOB_COUNT = 8;
+const vertexSource = (
+  /* glsl */
+  `#version 300 es
+// Fullscreen triangle — no buffers, three vertices from gl_VertexID.
+void main() {
+  vec2 p = vec2((gl_VertexID << 1) & 2, gl_VertexID & 2);
+  gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+}
+`
+);
+const fragmentSource = (
+  /* glsl */
+  `#version 300 es
+precision highp float;
+
+uniform vec2  u_resolution;  // drawing-buffer size in pixels
+uniform float u_time;        // field time, seconds (speed applied JS-side)
+uniform vec3  u_color[${BLOB_COUNT}];  // linear RGB per blob
+uniform vec4  u_blob[${BLOB_COUNT}];   // xy = centre, z = sigma, w = emission weight
+uniform vec4  u_motion[${BLOB_COUNT}]; // xy = angular speeds, zw = phases
+uniform float u_intensity;   // peak-alpha ceiling
+uniform float u_warp;        // domain-warp strength
+uniform float u_scale;       // noise frequency
+uniform float u_grain;       // film-grain strength
+uniform float u_streak;      // anisotropic stretch: 0 = blobs, 1 = light streams
+uniform vec2  u_mouse;       // pointer in field coordinates (smoothed JS-side)
+uniform float u_mvel;        // smoothed pointer speed, width units/s
+uniform float u_react;       // cursor-reactivity strength
+
+out vec4 outColor;
+
+// Integer hash — WebGL2 has real uint ops, so no fract(sin()) precision
+// lottery on mobile GPUs.
+uint ihash(uvec2 p) {
+  p = p * uvec2(73333u, 7777u) ^ (p.yx >> 3u);
+  uint h = p.x ^ (p.y * 2654435761u);
+  h ^= h >> 15u;
+  h *= 2246822519u;
+  h ^= h >> 13u;
+  return h;
+}
+
+float rnd(ivec2 p) {
+  return float(ihash(uvec2(p)) >> 8) * (1.0 / 16777216.0);
+}
+
+float vnoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);
+  ivec2 c = ivec2(i);
+  return mix(
+    mix(rnd(c), rnd(c + ivec2(1, 0)), u.x),
+    mix(rnd(c + ivec2(0, 1)), rnd(c + ivec2(1, 1)), u.x),
+    u.y
+  );
+}
+
+// 3 octaves; a 4th is invisible at this softness.
+float fbm(vec2 p) {
+  float s = 0.0;
+  float a = 0.5;
+  for (int i = 0; i < 3; i++) {
+    s += a * vnoise(p);
+    p = p * 2.02 + vec2(17.0, 9.0);
+    a *= 0.5;
+  }
+  return s;
+}
+
+void main() {
+  // CSS coordinate space: origin at container centre, one unit = width,
+  // y running downward.
+  vec2 p = (gl_FragCoord.xy - 0.5 * u_resolution) / u_resolution.x;
+  p.y = -p.y;
+
+  // Light-stream axis: a fixed diagonal. Distances across the axis are
+  // magnified before the Gaussian, so every source stretches along it and
+  // the field reads as rays instead of discs.
+  float ca = cos(0.5);
+  float sa = sin(0.5);
+  mat2 toStreak = mat2(ca, -sa, sa, ca);
+  float squeeze = 1.0 + u_streak * 4.0;
+
+  // Domain warp: the field flows rather than drifts. The noise is sampled
+  // in the same anisotropic space, so the flow lines follow the streams.
+  float t = u_time;
+  vec2 ps = toStreak * p;
+  ps.y *= squeeze;
+  vec2 q = vec2(
+    fbm(ps * u_scale + vec2(0.0, t * 0.030)),
+    fbm(ps * u_scale + vec2(5.2, 1.3) - t * 0.024)
+  );
+  vec2 w = p + u_warp * (q - 0.5);
+
+  // Cursor wake: a smooth vortex around the pointer, amplified by speed.
+  // The displacement is built from the *unnormalised* offset so it falls to
+  // zero at the cursor itself. Normalising here (md/mr) made the direction
+  // spin through 360 degrees at full strength across the centre pixel, which
+  // rendered as a pinch — a cone converging to a point.
+  vec2 md = p - u_mouse;
+  float mr2 = dot(md, md);
+  float minf = exp(-mr2 / (2.0 * 0.22 * 0.22));
+  vec2 swirl = vec2(-md.y, md.x);
+  // smoothstep, not min(): a hard clamp stepped visibly as speed crossed it.
+  float stir = 0.25 + 1.3 * smoothstep(0.0, 0.8, u_mvel);
+  w += u_react * minf * stir * (swirl * 0.9 + md * 0.35);
+
+  // Accumulate true Gaussians in linear space. Positive weights emit;
+  // negative weights absorb (shadows — the eclipse disc).
+  vec3 acc = vec3(0.0);
+  float cov = 0.0;
+  float shade = 0.0;
+  for (int i = 0; i < ${BLOB_COUNT}; i++) {
+    vec2 c = u_blob[i].xy + 0.045 * vec2(
+      cos(u_motion[i].x * t + u_motion[i].z),
+      sin(u_motion[i].y * t + u_motion[i].w)
+    );
+    vec2 d = toStreak * (w - c);
+    d.y *= squeeze;
+    float s = u_blob[i].z;
+    float g = exp(-dot(d, d) / (2.0 * s * s));
+    float wgt = u_blob[i].w;
+    if (wgt >= 0.0) {
+      acc += u_color[i] * (g * wgt);
+      cov += g * wgt;
+    } else {
+      shade += g * -wgt;
+    }
+  }
+
+  // Glow trail: wider and softer than the swirl, and mostly velocity-driven,
+  // so a resting cursor does not park a bright dot on the field.
+  //
+  // The wake brightens whatever colour it is passing over rather than adding
+  // one of its own. Injecting u_color[0] meant the trail always wore the
+  // first blob's token — gold in the site palette, violet in beam — which
+  // read as a stray colour with no relationship to the field beneath it.
+  // Weighting by the local hue keeps the wake colour-neutral: it reads as
+  // light falling on the field, and it stays correct for any palette.
+  vec3 local = acc / max(cov, 1e-4);
+  float gfall = exp(-mr2 / (2.0 * 0.3 * 0.3));
+  float glow = u_react * gfall * (0.12 + 0.5 * smoothstep(0.0, 0.8, u_mvel));
+  acc += local * glow;
+  cov += glow;
+
+  vec3 lin = acc / max(cov, 1e-4);
+  float lit = max(cov - shade, 0.0);
+  float alpha = u_intensity * (1.0 - exp(-lit * 0.9));
+
+  vec3 srgb = pow(max(lin, vec3(0.0)), vec3(1.0 / 2.2));
+
+  // Film grain: animated hash noise. At u_grain 0 this degenerates to the
+  // ±1/255 dither that kills banding, so the two share one lookup.
+  uvec2 gp = uvec2(gl_FragCoord.xy) + uvec2(
+    uint(fract(t * 7.31) * 1024.0) * 7919u,
+    uint(fract(t * 3.17) * 1024.0) * 104729u
+  );
+  float gr = float(ihash(gp) & 255u) / 255.0 - 0.5;
+  srgb += gr * (1.0 / 255.0 + u_grain * 0.35);
+  // A small grain-driven alpha floor lets the sparkle read even where the
+  // field itself is empty (the reference's grainy dark scene).
+  float grainFloor = u_grain * 0.1 * (gr + 0.5);
+  alpha = clamp(alpha * (1.0 + gr * u_grain * 0.5) + grainFloor, 0.0, 1.0);
+  srgb = clamp(srgb, 0.0, 1.0);
+
+  // Premultiplied output (context is created with premultipliedAlpha: true).
+  outColor = vec4(srgb * alpha, alpha);
+}
+`
+);
+export {
+  BLOB_COUNT,
+  fragmentSource,
+  vertexSource
+};

package/components/ShaderField/useShaderField.d.ts

@@ -0,0 +1,86 @@
+import { RefObject } from 'react';
+/** The seven tuneable properties of the field. */
+export interface ShaderParams {
+    /** Overall opacity of the field, 0.1–1. */
+    intensity: number;
+    /** Domain-warp strength: how much fbm noise bends the field, 0–0.5. */
+    warp: number;
+    /** Noise frequency. Higher values give finer, busier structure, 0.5–6. */
+    scale: number;
+    /** Drift-rate multiplier on every blob's period, 0–4. */
+    speed: number;
+    /** Dither/film-grain amplitude, 0–0.4. Also what kills 8-bit banding. */
+    grain: number;
+    /** Anisotropic stretch: 0 renders discs, 1 renders diagonal streams, 0–1. */
+    streak: number;
+    /**
+     * Cursor-wake strength, 0–1. Defaults to 0 — the interaction is built and
+     * dormant, not absent. Raising it turns on the swirl and glow trail, and
+     * with them the loop's step up from 30fps to 60fps while a wake is alive.
+     */
+    react: number;
+}
+/**
+ * One light source in the field.
+ *
+ * The coordinate space is the shader's (see field.glsl): origin at the
+ * container centre, one unit = container width, y running downward. Centres
+ * are constants — nothing here is recomputed on resize.
+ */
+export interface ShaderBlob {
+    /**
+     * Semantic colour token, read from the canvas's computed style at runtime,
+     * so the field re-themes with `data-theme` and with any scoped custom-
+     * property override. A token nothing defines resolves to no colour — an
+     * invisible source, never an error.
+     */
+    token: string;
+    /** Disc diameter in container-width units. */
+    size: number;
+    /** Centre offset from the container centre, width units. */
+    cx: number;
+    /** Centre offset from the container centre, width units. */
+    cy: number;
+    /** Drift cycle in seconds, before `speed` is applied. */
+    period: number;
+    /** Phase offset, so sources never move in lockstep. */
+    phase: number;
+    /**
+     * Emission weight. Positive emits light; negative absorbs it, giving a
+     * shadow that occludes whatever shines behind it.
+     */
+    weight: number;
+}
+/**
+ * The shipped look: seven parameters tuned by eye, cursor wake off. Spread it
+ * and override the one or two you want rather than restating the set.
+ */
+export declare const DEFAULT_SHADER_PARAMS: ShaderParams;
+/**
+ * The default composition: eight sources on core accent tokens, filling
+ * BLOB_COUNT exactly.
+ *
+ * `--color-action-primary-bg` is deliberately absent. The action colour is
+ * reserved for CTAs and focus rings, and a full-viewport decorative field is
+ * precisely the use that would stop it meaning "click here" — so the last
+ * source takes `--color-core-ui-secondary` instead.
+ */
+export declare const DEFAULT_SHADER_BLOBS: readonly ShaderBlob[];
+/**
+ * Live tunables. Changing them never rebuilds the GL state — the render loop
+ * reads them through a ref, and a paused field redraws one frame.
+ */
+export interface ShaderFieldParams extends ShaderParams {
+    /** The colour-source table; swap it to change composition live. */
+    blobs: readonly ShaderBlob[];
+}
+export interface ShaderFieldState {
+    /** False once getContext('webgl2') has returned null — the caller should
+     *  leave its CSS fallback painted. */
+    supported: boolean;
+    /** True once the first frame has been drawn. */
+    active: boolean;
+}
+export declare function parseColor(value: string): [number, number, number] | null;
+export declare function srgbToLinear(c: number): number;
+export declare function useShaderField(canvasRef: RefObject<HTMLCanvasElement | null>, params: ShaderFieldParams, enabled?: boolean): ShaderFieldState;