panelui-native 0.110.0 → 0.111.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -51,6 +51,7 @@ import {
51
51
  useEffect,
52
52
  useImperativeHandle,
53
53
  useMemo,
54
+ useRef,
54
55
  useState,
55
56
  type ReactNode,
56
57
  type Ref,
@@ -81,6 +82,7 @@ import { Button, type ButtonProps } from '../button';
81
82
  import {
82
83
  IDENTITY,
83
84
  baseSize,
85
+ coversMask,
84
86
  maskPath,
85
87
  nextQuarterTurn,
86
88
  normalizeDegrees,
@@ -89,6 +91,7 @@ import {
89
91
  settle,
90
92
  sourceCrop,
91
93
  zoomAbout,
94
+ type CropBounds,
92
95
  type CropFrame,
93
96
  type CropShape,
94
97
  type CropState,
@@ -165,6 +168,17 @@ function loadPicker(): PickerModule | null {
165
168
  }
166
169
  }
167
170
 
171
+ /** `react-native-view-shot`'s capture function, or null when it is not installed. */
172
+ function loadCapture(): ((view: unknown, options: unknown) => Promise<string>) | null {
173
+ try {
174
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
175
+ const mod = require('react-native-view-shot');
176
+ return (mod?.captureRef as (view: unknown, options: unknown) => Promise<string>) ?? null;
177
+ } catch {
178
+ return null;
179
+ }
180
+ }
181
+
168
182
  /** True when `crop()` can write an image, because `expo-image-manipulator` is installed. */
169
183
  export const hasAvatarCropperExport = loadManipulator()?.ImageManipulator != null;
170
184
 
@@ -237,7 +251,11 @@ export interface AvatarCropOptions {
237
251
  * pixels than this is written at its own size rather than scaled up.
238
252
  */
239
253
  size?: number;
240
- /** Default `'jpeg'`. Use `'png'` to keep transparency out of the question entirely. */
254
+ /**
255
+ * Default `'jpeg'`, or `'png'` when `background` is `'transparent'` so the
256
+ * transparency survives. A crop with a background is written as PNG or
257
+ * JPEG, so `'webp'` is written as PNG there.
258
+ */
241
259
  format?: 'jpeg' | 'png' | 'webp';
242
260
  /** Quality, 0–1, for JPEG and WebP. Default 0.9. */
243
261
  compress?: number;
@@ -249,13 +267,16 @@ export interface AvatarCropperHandle {
249
267
  * every shape; draw it in a round `Avatar` to show it as a circle.
250
268
  *
251
269
  * Needs the optional `expo-image-manipulator`, and throws if it is not
252
- * installed — use `getCrop()` then.
270
+ * installed — use `getCrop()` then. A crop with part of `background` in it
271
+ * (only possible with `cover` off) is drawn and captured instead, and needs
272
+ * the optional `react-native-view-shot`.
253
273
  */
254
274
  crop(options?: AvatarCropOptions): Promise<AvatarCropResult>;
255
275
  /**
256
276
  * The rectangle the mask covers, in the source's pixels, after turning the
257
277
  * source by `rotation` degrees clockwise. Null until the photo has been
258
- * measured and laid out.
278
+ * measured and laid out. With `cover` off it can reach past the turned
279
+ * image's edges; whatever lies outside is `background`.
259
280
  */
260
281
  getCrop(): SourceCrop | null;
261
282
  /** Turn a quarter clockwise, or a quarter back with `-1`. */
@@ -274,6 +295,26 @@ export interface AvatarCropperProps extends ViewProps {
274
295
  shape?: CropShape;
275
296
  /** How far the photo can be zoomed past filling the mask. Default 5. */
276
297
  maxZoom?: number;
298
+ /**
299
+ * Keep the photo covering the whole outline. Default true: let go past an
300
+ * edge, or zoom out too far, and it springs back to fill it.
301
+ *
302
+ * Set it to false to let the photo be zoomed out smaller than the outline,
303
+ * down to `minZoom`. The space around it is filled with `background`, on
304
+ * screen and in the image `crop()` writes.
305
+ */
306
+ cover?: boolean;
307
+ /**
308
+ * With `cover` off, how small the photo can get: its long side as a
309
+ * fraction of the outline's width. Default 0.5.
310
+ */
311
+ minZoom?: number;
312
+ /**
313
+ * What fills the outline around a photo smaller than it, with `cover` off.
314
+ * Any colour React Native accepts, or `'transparent'` — written out as PNG
315
+ * so it stays transparent. Default: the theme's background colour.
316
+ */
317
+ background?: string;
277
318
  /** Space between the mask and the canvas's shorter side, in points. Default 24. */
278
319
  inset?: number;
279
320
  className?: string;
@@ -283,7 +324,11 @@ export interface AvatarCropperProps extends ViewProps {
283
324
 
284
325
  interface CropperContextValue {
285
326
  shape: CropShape;
286
- maxZoom: number;
327
+ bounds: CropBounds;
328
+ /** The resolved fill around a photo smaller than the outline. */
329
+ fill: string;
330
+ /** A crop being drawn for capture, while `crop()` is waiting on it. */
331
+ stage: ExportJob | null;
287
332
  inset: number;
288
333
  source: AvatarCropperSource;
289
334
  /** The source's upright size, once known. */
@@ -322,6 +367,9 @@ function AvatarCropperRoot(
322
367
  source,
323
368
  shape = 'circle',
324
369
  maxZoom = 5,
370
+ cover = true,
371
+ minZoom = 0.5,
372
+ background,
325
373
  inset = 24,
326
374
  className,
327
375
  children,
@@ -336,6 +384,14 @@ function AvatarCropperRoot(
336
384
  const [canvas, setCanvasState] = useState<Size | null>(null);
337
385
  const [measured, setMeasured] = useState<Size | null>(null);
338
386
  const [summary, setSummary] = useState(describe(IDENTITY));
387
+ const [stage, setStage] = useState<ExportJob | null>(null);
388
+ const backgroundToken = useCSSVariable('--color-background');
389
+ const fill =
390
+ background ?? (typeof backgroundToken === 'string' ? backgroundToken : '#ffffff');
391
+ const bounds = useMemo<CropBounds>(
392
+ () => ({ shape, maxZoom, cover, minZoom }),
393
+ [shape, maxZoom, cover, minZoom]
394
+ );
339
395
 
340
396
  const { uri, width, height } = source;
341
397
  const sourceSize =
@@ -388,7 +444,7 @@ function AvatarCropperRoot(
388
444
  const animateTo = useCallback(
389
445
  (target: CropState, timed: boolean) => {
390
446
  if (!frame) return;
391
- const next = settle(target, shape, frame, maxZoom);
447
+ const next = settle(target, bounds, frame);
392
448
  const run = (value: number) =>
393
449
  timed ? withTiming(value, { duration: TURN_DURATION }) : withSpring(value, SETTLE_SPRING);
394
450
  x.value = run(next.x);
@@ -397,7 +453,7 @@ function AvatarCropperRoot(
397
453
  rotation.value = run(next.rotation);
398
454
  setSummary(describe(next));
399
455
  },
400
- [frame, shape, maxZoom, x, y, scale, rotation]
456
+ [frame, bounds, x, y, scale, rotation]
401
457
  );
402
458
 
403
459
  const settleNow = useCallback(() => animateTo(read(), false), [animateTo, read]);
@@ -424,10 +480,16 @@ function AvatarCropperRoot(
424
480
  [animateTo, read]
425
481
  );
426
482
 
483
+ const settled = useCallback(
484
+ (): CropState | null => (frame ? settle(read(), bounds, frame) : null),
485
+ [frame, bounds, read]
486
+ );
487
+
427
488
  const getCrop = useCallback((): SourceCrop | null => {
428
- if (!frame || !sourceSize) return null;
429
- return sourceCrop(settle(read(), shape, frame, maxZoom), frame, sourceSize);
430
- }, [frame, sourceSize, read, shape, maxZoom]);
489
+ const state = settled();
490
+ if (!state || !frame || !sourceSize) return null;
491
+ return sourceCrop(state, frame, sourceSize, coversMask(state, shape, frame));
492
+ }, [settled, frame, sourceSize, shape]);
431
493
 
432
494
  useImperativeHandle(
433
495
  ref,
@@ -435,7 +497,46 @@ function AvatarCropperRoot(
435
497
  getCrop,
436
498
  rotate,
437
499
  reset,
438
- async crop({ size = 1024, format = 'jpeg', compress = 0.9 } = {}) {
500
+ async crop({ size = 1024, format, compress = 0.9 } = {}) {
501
+ const state = settled();
502
+ const rect = getCrop();
503
+ if (!state || !frame || !rect || !sourceSize) {
504
+ throw new Error('AvatarCropper.crop: the photo has not been measured and laid out yet.');
505
+ }
506
+ const transparent = fill === 'transparent';
507
+ const output = format ?? (transparent ? 'png' : 'jpeg');
508
+ const side = Math.min(size, rect.width);
509
+
510
+ if (!coversMask(state, shape, frame)) {
511
+ // Part of the outline is background, which the manipulator cannot
512
+ // paint on a phone. Draw the crop as the screen does, off to one
513
+ // side, and capture that instead.
514
+ const capture = loadCapture();
515
+ if (!capture) {
516
+ throw new Error(
517
+ 'AvatarCropper.crop: a photo smaller than the outline is written with ' +
518
+ 'react-native-view-shot. Install it with: npx expo install react-native-view-shot'
519
+ );
520
+ }
521
+ return new Promise<AvatarCropResult>((resolve, reject) => {
522
+ setStage({
523
+ state,
524
+ side,
525
+ format: output === 'jpeg' ? 'jpg' : 'png',
526
+ compress,
527
+ capture,
528
+ resolve: (result) => {
529
+ setStage(null);
530
+ resolve(result);
531
+ },
532
+ reject: (error) => {
533
+ setStage(null);
534
+ reject(error);
535
+ },
536
+ });
537
+ });
538
+ }
539
+
439
540
  const manipulator = loadManipulator()?.ImageManipulator;
440
541
  if (!manipulator) {
441
542
  throw new Error(
@@ -443,10 +544,6 @@ function AvatarCropperRoot(
443
544
  'npx expo install expo-image-manipulator — or use getCrop() to crop elsewhere.'
444
545
  );
445
546
  }
446
- const rect = getCrop();
447
- if (!rect || !sourceSize) {
448
- throw new Error('AvatarCropper.crop: the photo has not been measured and laid out yet.');
449
- }
450
547
  // Redraw upright first. The turn and the cut both read raw pixels,
451
548
  // and a camera photo often keeps its orientation in a flag instead.
452
549
  const context = manipulator.manipulate(uri).resize({ width: sourceSize.width });
@@ -457,17 +554,19 @@ function AvatarCropperRoot(
457
554
  width: rect.width,
458
555
  height: rect.height,
459
556
  });
460
- if (size < rect.width) context.resize({ width: size, height: size });
557
+ if (side < rect.width) context.resize({ width: side, height: side });
461
558
  const rendered = await context.renderAsync();
462
- return rendered.saveAsync({ format, compress });
559
+ return rendered.saveAsync({ format: output, compress });
463
560
  },
464
561
  }),
465
- [getCrop, rotate, reset, sourceSize, uri]
562
+ [getCrop, settled, rotate, reset, sourceSize, uri, frame, shape, fill]
466
563
  );
467
564
 
468
565
  const value: CropperContextValue = {
469
566
  shape,
470
- maxZoom,
567
+ bounds,
568
+ fill,
569
+ stage,
471
570
  inset,
472
571
  source,
473
572
  sourceSize,
@@ -499,6 +598,106 @@ const AvatarCropperForwarded = forwardRef<AvatarCropperHandle, AvatarCropperProp
499
598
  );
500
599
  AvatarCropperForwarded.displayName = 'AvatarCropper';
501
600
 
601
+ interface ExportJob {
602
+ state: CropState;
603
+ /** Side of the image to write, in pixels. */
604
+ side: number;
605
+ format: 'png' | 'jpg';
606
+ compress: number;
607
+ capture: (view: unknown, options: unknown) => Promise<string>;
608
+ resolve: (result: AvatarCropResult) => void;
609
+ reject: (error: unknown) => void;
610
+ }
611
+
612
+ /**
613
+ * The crop drawn on its own, for capture: a square of the background with the
614
+ * photo placed in it exactly as the canvas places it under the outline.
615
+ *
616
+ * It sits directly under the outline, at the outline's size, beneath the
617
+ * canvas's own drawing of the same thing — so it is never seen, whatever
618
+ * surrounds the cropper. The capture reads the view's own drawing, not what is
619
+ * on screen above it, and scales it to the size asked for.
620
+ */
621
+ function ExportStage({
622
+ job,
623
+ frame,
624
+ uri,
625
+ fill,
626
+ left,
627
+ top,
628
+ }: {
629
+ job: ExportJob;
630
+ frame: CropFrame;
631
+ uri: string;
632
+ fill: string;
633
+ left: number;
634
+ top: number;
635
+ }) {
636
+ const ref = useRef<View>(null);
637
+ const started = useRef(false);
638
+ const side = frame.mask;
639
+ const { width, height } = frame.image;
640
+ const { state } = job;
641
+
642
+ const capture = () => {
643
+ if (started.current) return;
644
+ started.current = true;
645
+ job
646
+ .capture(ref.current, {
647
+ format: job.format,
648
+ quality: job.compress,
649
+ result: 'tmpfile',
650
+ width: job.side,
651
+ height: job.side,
652
+ })
653
+ .then((uri) => job.resolve({ uri, width: job.side, height: job.side }))
654
+ .catch(job.reject);
655
+ };
656
+
657
+ return (
658
+ <View
659
+ ref={ref}
660
+ collapsable={false}
661
+ pointerEvents="none"
662
+ importantForAccessibility="no-hide-descendants"
663
+ accessibilityElementsHidden
664
+ style={{
665
+ position: 'absolute',
666
+ left,
667
+ top,
668
+ width: side,
669
+ height: side,
670
+ overflow: 'hidden',
671
+ backgroundColor: fill,
672
+ }}
673
+ >
674
+ <View
675
+ style={{
676
+ position: 'absolute',
677
+ left: (side - width) / 2,
678
+ top: (side - height) / 2,
679
+ width,
680
+ height,
681
+ transform: [
682
+ { translateX: state.x },
683
+ { translateY: state.y },
684
+ { rotate: `${state.rotation}deg` },
685
+ { scale: state.scale },
686
+ ],
687
+ }}
688
+ >
689
+ <Image
690
+ source={{ uri }}
691
+ style={{ width, height }}
692
+ resizeMode="cover"
693
+ onLoad={() => requestAnimationFrame(capture)}
694
+ onError={() => job.reject(new Error('AvatarCropper.crop: the photo failed to load.'))}
695
+ />
696
+ </View>
697
+ </View>
698
+ );
699
+ }
700
+
502
701
  // ---------------------------------------------------------------------------
503
702
  // Canvas
504
703
  // ---------------------------------------------------------------------------
@@ -522,7 +721,9 @@ function AvatarCropperCanvas({
522
721
  }: AvatarCropperCanvasProps) {
523
722
  const {
524
723
  shape,
525
- maxZoom,
724
+ bounds,
725
+ fill,
726
+ stage,
526
727
  source,
527
728
  frame,
528
729
  canvas,
@@ -552,7 +753,7 @@ function AvatarCropperCanvas({
552
753
 
553
754
  const shown = useDerivedValue((): CropState => {
554
755
  const raw = { x: x.value, y: y.value, scale: scale.value, rotation: rotation.value };
555
- return frame ? present(raw, shape, frame, maxZoom) : raw;
756
+ return frame ? present(raw, bounds, frame) : raw;
556
757
  });
557
758
 
558
759
  const imageStyle = useAnimatedStyle(() => ({
@@ -584,8 +785,12 @@ function AvatarCropperCanvas({
584
785
  const bound = (state: CropState) => {
585
786
  'worklet';
586
787
  if (!frame) return state;
587
- const lowest = 1 / OVERSHOOT / 2;
588
- const next = { ...state, scale: Math.min(Math.max(state.scale, lowest), maxZoom * OVERSHOOT) };
788
+ // A guard against running away, not a bound: `present` does the bounding.
789
+ const lowest = 0.05;
790
+ const next = {
791
+ ...state,
792
+ scale: Math.min(Math.max(state.scale, lowest), bounds.maxZoom * OVERSHOOT),
793
+ };
589
794
  const limit = Math.max(image.width, image.height) * next.scale;
590
795
  next.x = Math.min(Math.max(next.x, -limit), limit);
591
796
  next.y = Math.min(Math.max(next.y, -limit), limit);
@@ -656,7 +861,7 @@ function AvatarCropperCanvas({
656
861
  });
657
862
 
658
863
  return Gesture.Simultaneous(pan, pinch, turn);
659
- }, [active, x, y, scale, rotation, settleNow, frame, image.width, image.height, maxZoom, W, H]);
864
+ }, [active, x, y, scale, rotation, settleNow, frame, image.width, image.height, bounds, W, H]);
660
865
 
661
866
  const onAccessibilityAction = useCallback(
662
867
  (event: AccessibilityActionEvent) => {
@@ -704,6 +909,29 @@ function AvatarCropperCanvas({
704
909
  onAccessibilityAction={onAccessibilityAction}
705
910
  {...props}
706
911
  >
912
+ {stage && frame && W > 0 ? (
913
+ <ExportStage
914
+ job={stage}
915
+ frame={frame}
916
+ uri={source.uri}
917
+ fill={fill}
918
+ left={(W - mask) / 2}
919
+ top={(H - mask) / 2}
920
+ />
921
+ ) : null}
922
+ {!bounds.cover && frame && W > 0 && fill !== 'transparent' ? (
923
+ <View
924
+ pointerEvents="none"
925
+ style={{
926
+ position: 'absolute',
927
+ left: (W - mask) / 2,
928
+ top: (H - mask) / 2,
929
+ width: mask,
930
+ height: mask,
931
+ backgroundColor: fill,
932
+ }}
933
+ />
934
+ ) : null}
707
935
  {frame && W > 0 ? (
708
936
  <Animated.View
709
937
  pointerEvents="none"