panelui-native 0.82.0 → 0.83.0

package/src/components/image-generation/dot-field.ts

@@ -25,6 +25,15 @@ export const DOT_LIT_RADIUS = 1.9;
 /** How visible the resting grid is, under everything. */
 export const DOT_REST_OPACITY = 0.16;
 
+/**
+ * How visible the lit dots are, together.
+ *
+ * "Together" is the operative word: they are drawn as two layers fading into
+ * one another, and this is what the pair composites to, not what either one
+ * carries. {@link crossfadeAlphas} is what holds that true.
+ */
+export const LIT_OPACITY = 0.9;
+
 /** How many still frames one loop is drawn as. */
 export const FRAMES = 24;
 
@@ -118,11 +127,20 @@ export function influenceAt(distance: number, radius: number): number {
 /**
  * Where the light is at a phase of the loop, and how wide it reaches.
  *
- * `drift` wanders around the middle — two periods that do not divide into each
- * other, so the path never closes into a loop the eye can learn, and small
- * amplitudes because a light that reaches the corners stops reading as one
- * source. `pulse` is a ring leaving the centre. `scan` crosses as a band, which
- * is the same maths with the light infinitely tall.
+ * `drift` wanders around the middle on a figure-eight: one horizontal pass to
+ * two vertical, so the path arrives back where it started and the loop has no
+ * seam in it. The amplitudes are small because a light that reaches the corners
+ * stops reading as one source.
+ *
+ * The two frequencies used not to divide into each other, on the reasoning that
+ * a path which never closes is one the eye cannot learn. It closes anyway —
+ * every animation here restarts at the end of its period — so all that bought
+ * was a jump of four normal steps, once a pass. A figure-eight is not a shape
+ * anybody follows over four seconds of soft light on a dot grid.
+ *
+ * `pulse` is a ring leaving the centre, and has expanded past the last dot
+ * before it restarts, so it fades out rather than snapping back. `scan` crosses
+ * as a band, which is the same maths with the light infinitely tall.
  */
 function lightAt(
   animation: DotFieldAnimation,
@@ -157,7 +175,7 @@ function lightAt(
 
   return {
     x: width / 2 + Math.sin(turn) * width * 0.26,
-    y: height / 2 + Math.cos(turn * 1.37) * height * 0.22,
+    y: height / 2 + Math.cos(turn * 2) * height * 0.22,
     radius: short * 0.42,
     ring: 0,
   };
@@ -169,19 +187,25 @@ function lightAt(
  * Only the dots the light actually reaches are in it — the rest are already
  * drawn by the resting grid underneath, so this is a fraction of the field
  * rather than all of it.
+ *
+ * `points` is the same grid {@link anchors} would build, passed in by a caller
+ * that is about to ask for every frame of a loop. Building it here instead cost
+ * a fresh array of several hundred pairs per frame, to arrive at the identical
+ * grid twenty-four times over.
  */
 export function litPath(
   width: number,
   height: number,
   phase: number,
-  animation: DotFieldAnimation = 'drift'
+  animation: DotFieldAnimation = 'drift',
+  points?: [number, number][]
 ): string {
   if (width <= 0 || height <= 0) return '';
 
   const light = lightAt(animation, phase, width, height);
   let path = '';
 
-  for (const [x, y] of anchors(width, height)) {
+  for (const [x, y] of points ?? anchors(width, height)) {
     const deltaX = x - light.x;
     const deltaY = Number.isNaN(light.y) ? 0 : y - light.y;
     const distance = Math.abs(
@@ -206,8 +230,9 @@ export function litFrames(
   height: number,
   animation: DotFieldAnimation = 'drift'
 ): string[] {
+  const points = width > 0 && height > 0 ? anchors(width, height) : [];
   return Array.from({ length: FRAMES }, (_unused, index) =>
-    litPath(width, height, index / FRAMES, animation)
+    litPath(width, height, index / FRAMES, animation, points)
   );
 }
 
@@ -224,3 +249,34 @@ export function frameAt(time: number, animation: DotFieldAnimation): number {
   const phase = (time % PERIOD[animation]) / PERIOD[animation];
   return Math.min(FRAMES - 1, Math.floor(phase * FRAMES));
 }
+
+/**
+ * Where a moment falls in the loop, as a frame index with its fraction kept.
+ *
+ * {@link frameAt} rounds this down, and rounding it down is what made the field
+ * a flipbook: twenty-four pictures spread over the period, which on the slowest
+ * animation is a new one every 175ms however fast the screen refreshes. The
+ * fraction is what the two layers cross-fade on, so the light moves at the rate
+ * the display can draw rather than the rate the frames were built at.
+ */
+export function framePhase(time: number, animation: DotFieldAnimation): number {
+  'worklet';
+  return ((time % PERIOD[animation]) / PERIOD[animation]) * FRAMES;
+}
+
+/**
+ * What the outgoing and incoming layers are worth, a fraction `t` of the way
+ * from one frame to the next.
+ *
+ * Not `[1 - t, t]`. The layers are drawn over one another, so a dot lit in both
+ * of them composites to `1 - (1-a)(1-b)`, and two half-strength copies of it
+ * come to 0.70 rather than 0.90 — the field dips a fifth in the middle of every
+ * step, which six steps a second turns into a flicker. So only the outgoing
+ * layer ramps, and the incoming one is solved for: whatever leaves the pair at
+ * {@link LIT_OPACITY} the whole way across.
+ */
+export function crossfadeAlphas(t: number): [number, number] {
+  'worklet';
+  const out = LIT_OPACITY * (1 - t);
+  return [out, 1 - (1 - LIT_OPACITY) / (1 - out)];
+}

package/src/components/image-generation/index.tsx

@@ -15,14 +15,22 @@
  *
  * ## The dot field
  *
- * A grid of dots with a soft band of light travelling across it. Each column
- * is one animated view holding its own dots, so a field of five hundred dots
- * costs twenty-two worklets a frame rather than five hundred — the dots inside
- * a column never move independently of it, and at this scale nobody can tell.
+ * A grid of dots with a soft light moving through it, drawn as three layers:
+ * the field at rest, and two copies of the lit dots fading into one another.
  *
- * The per-dot brightness underneath the band is fixed, and comes from the
- * dot's own coordinates. Without it the field reads as clean vertical stripes
- * sweeping past; with it, it reads as the individual dots lighting up.
+ * Every picture the loop will ever draw is built when the box is measured, so
+ * running it hands over a string that already exists. That leaves twenty-four
+ * pictures to spread across the pass, which on its own is a flipbook — a new
+ * one every 175ms, however fast the screen refreshes. The two layers are what
+ * fills the gap: one holds the frame being left and one the frame being
+ * arrived at, and only their opacities move, which the compositor animates at
+ * the display's own rate without the drawing being touched.
+ *
+ * They are opacities on views rather than on the dots, and that is not a
+ * detail. A value that changes every frame sitting beside the path string
+ * pushes the path every frame too, and every push of a path is a re-parse of
+ * several hundred subpaths — which is the cost this whole arrangement exists
+ * to avoid. Kept apart, the path is pushed only when it actually changes.
  *
  * ## What arrives, and when
  *
@@ -34,11 +42,11 @@
  *
  * ## Reduced motion
  *
- * The band stops, and the field is drawn at one still frame of itself. A
+ * The light stops, and the field holds wherever the clock was left. A
  * placeholder that shows nothing is indistinguishable from a component that
  * failed to load, so this is a quieter picture rather than an empty one.
  */
-import { useEffect, useId, useMemo, useState, type ReactNode } from 'react';
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
 import {
   Pressable,
   StyleSheet,
@@ -61,13 +69,14 @@ import Animated, {
 } from 'react-native-reanimated';
 import { tv } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
-import { useDirectionSign } from '../../hooks/use-direction';
 import { AlertTriangleIcon, CheckIcon, RotateCcwIcon } from '../../icons';
 import { Text } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 import {
   DOT_REST_OPACITY,
-  frameAt,
+  FRAMES,
+  crossfadeAlphas,
+  framePhase,
   gridPath,
   litFrames,
   type DotFieldAnimation,
@@ -241,8 +250,21 @@ function ImageGenerationField({
    * light is somewhere legible rather than dead centre or absent, which is the
    * difference between "not animating" and "failed to load".
    */
-  const animatedProps = useAnimatedProps(() => ({
-    d: frames[frameAt(clock.value, animation)] ?? '',
+  const slotA = useAnimatedProps(() => ({
+    d: frames[Math.floor(framePhase(clock.value, animation))] ?? '',
+  }));
+  const slotB = useAnimatedProps(() => ({
+    d: frames[(Math.floor(framePhase(clock.value, animation)) + 1) % FRAMES] ?? '',
+  }));
+
+  // Only these move between one frame and the next, and a view's opacity is a
+  // layer alpha — so the drawing underneath is composited again rather than
+  // drawn again.
+  const fadeOut = useAnimatedStyle(() => ({
+    opacity: crossfadeAlphas(framePhase(clock.value, animation) % 1)[0],
+  }));
+  const fadeIn = useAnimatedStyle(() => ({
+    opacity: crossfadeAlphas(framePhase(clock.value, animation) % 1)[1],
   }));
 
   const onLayout = (event: LayoutChangeEvent) => {
@@ -261,14 +283,41 @@ function ImageGenerationField({
       {...props}
     >
       {grid ? (
-        <Svg width={size.width} height={size.height}>
+        <>
           {/* The field at rest, under everything and never touched again. */}
-          <Path d={grid} fill={color} fillOpacity={DOT_REST_OPACITY} />
+          <Svg
+            width={size.width}
+            height={size.height}
+            style={StyleSheet.absoluteFill}
+          >
+            <Path d={grid} fill={color} fillOpacity={DOT_REST_OPACITY} />
+          </Svg>
           {/* The dots the light has reached, drawn larger over their own
               resting copies rather than instead of them — so a dot brightens
-              in place instead of appearing to move. */}
-          <AnimatedPath animatedProps={animatedProps} fill={color} fillOpacity={0.9} />
-        </Svg>
+              in place instead of appearing to move.
+
+              Two of them: the frame being left and the frame being arrived at.
+              Each carries its dots at full strength and the pair is brought to
+              LIT_OPACITY by the views, because what fades has to be the layer
+              and not the fill — see crossfadeAlphas for why the ramps are not
+              simply t and 1 - t. */}
+          <Animated.View
+            style={[StyleSheet.absoluteFill, fadeOut]}
+            pointerEvents="none"
+          >
+            <Svg width={size.width} height={size.height}>
+              <AnimatedPath animatedProps={slotA} fill={color} />
+            </Svg>
+          </Animated.View>
+          <Animated.View
+            style={[StyleSheet.absoluteFill, fadeIn]}
+            pointerEvents="none"
+          >
+            <Svg width={size.width} height={size.height}>
+              <AnimatedPath animatedProps={slotB} fill={color} />
+            </Svg>
+          </Animated.View>
+        </>
       ) : null}
     </View>
   );

package/src/native/index.ts

@@ -145,6 +145,20 @@ interface SwiftUIModifiers {
     cornerRadius?: number
   ) => unknown;
   controlSize: (size: 'mini' | 'small' | 'regular' | 'large' | 'extraLarge') => unknown;
+  /**
+   * Paints a sheet's own surface, rather than a background behind its content.
+   *
+   * It is the only way out of the material a sheet is drawn in by default, and
+   * it reaches what an ordinary background cannot: the grabber's strip at the
+   * top and the safe-area inset at the bottom, which belong to the sheet's
+   * chrome and not to anything hosted inside it.
+   *
+   * **iOS 16.4 and up.** Below that it is inert and the sheet keeps its
+   * material — the same shape as glass being inert below iOS 26, and the same
+   * trap: indistinguishable from the prop not working. Check the OS before
+   * changing any code on a report of "the colour did nothing".
+   */
+  presentationBackground: (color: string) => unknown;
 }
 
 let modifiersResolved = false;
@@ -165,3 +179,34 @@ export function getSwiftUIModifiers(): SwiftUIModifiers | null {
 
   return modifiers;
 }
+
+/**
+ * The Compose view modifiers — the other half of the same door.
+ *
+ * Android's toolkit has its own modifier system and its own vocabulary, so a
+ * modifier built for one platform is not a modifier the other can read. Where
+ * both are asked the same question the answers are written separately, here and
+ * above, rather than one being sent to both.
+ */
+interface ComposeModifiers {
+  background: (color: string) => unknown;
+}
+
+let composeResolved = false;
+let compose: ComposeModifiers | null = null;
+
+export function getComposeModifiers(): ComposeModifiers | null {
+  if (composeResolved) return compose;
+  composeResolved = true;
+
+  if (Platform.OS !== 'android') return null;
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    compose = require('@expo/ui/jetpack-compose/modifiers') as ComposeModifiers;
+  } catch {
+    compose = null;
+  }
+
+  return compose;
+}