@oxyhq/bloom 0.26.1 → 0.27.0

package/src/avatar/AvatarRing.tsx

@@ -0,0 +1,170 @@
+import React, { memo, useMemo } from 'react';
+import { View, StyleSheet } from 'react-native';
+
+import { Z_INDEX } from '../styles/z-index';
+import { getSvgModule } from './svg-module';
+import { SQUIRCLE_PATH } from './squircle-path';
+import type { AvatarRingGradientDirection, AvatarShape } from './types';
+
+// Module counter for unique gradient element ids — mirrors the `clipIdCounter`
+// pattern in `Avatar.tsx`. Deterministic (no `Math.random()`) so ids are stable
+// per mounted instance.
+let ringGradientIdCounter = 0;
+
+/**
+ * Size of the box the ring occupies. With `gap === 0` the ring overlays the
+ * avatar edge and the box equals the avatar size (footprint unchanged). With
+ * `gap > 0` the ring sits OUTSIDE the avatar, so the box grows and the avatar is
+ * centered inside it. Exported so `Avatar` reserves the same footprint with a
+ * single source for the geometry formula.
+ */
+export function getRingOuterSize(size: number, width: number, gap: number): number {
+  return gap > 0 ? size + 2 * (width + gap) : size;
+}
+
+interface AvatarRingProps {
+  /** Avatar diameter in px (the inner content size, before any gap). */
+  size: number;
+  /** Matches the avatar shape. */
+  shape: AvatarShape;
+  /** Solid ring: one color. Gradient ring: 2+ colors. */
+  colors: string | string[];
+  /** Ring stroke width in px. */
+  width: number;
+  /** Gap between the avatar edge and the ring (0 = overlay the edge). */
+  gap: number;
+  /** Gradient sweep direction for multi-color rings. */
+  gradientDirection: AvatarRingGradientDirection;
+}
+
+function gradientCoords(direction: AvatarRingGradientDirection) {
+  switch (direction) {
+    case 'horizontal':
+      return { x1: '0', y1: '0', x2: '1', y2: '0' };
+    case 'vertical':
+      return { x1: '0', y1: '0', x2: '0', y2: '1' };
+    case 'diagonal':
+    default:
+      return { x1: '0', y1: '0', x2: '1', y2: '1' };
+  }
+}
+
+/**
+ * Single ring primitive shared by the `live` indicator and the public `ring`
+ * prop. Renders either a solid or a gradient ring, for both `circle` and
+ * `squircle` avatars.
+ *
+ * - Solid circle → a plain bordered `<View>` (no `react-native-svg` needed).
+ * - Solid squircle → an SVG `<Path>` stroking the squircle outline.
+ * - Gradient (either shape) → an SVG `<LinearGradient>` stroke; degrades to a
+ *   solid ring of the first color when `react-native-svg` is unavailable (a
+ *   squircle then degrades to a circle border, matching the avatar's own no-SVG
+ *   circle fallback).
+ *
+ * Internal to the avatar family — not exported from the package.
+ */
+const AvatarRingComponent: React.FC<AvatarRingProps> = ({
+  size,
+  shape,
+  colors,
+  width,
+  gap,
+  gradientDirection,
+}) => {
+  const gradientId = useMemo(() => `bloom-ring-grad${ringGradientIdCounter++}`, []);
+
+  const colorList = Array.isArray(colors) ? colors : [colors];
+  const wantsGradient = colorList.length >= 2;
+  const solidColor = colorList[0] ?? '#000000';
+
+  const outer = getRingOuterSize(size, width, gap);
+  // The ring's visible band is always the outermost `width` px inside the outer
+  // box; when it degrades to a circle border it is a full circle → radius
+  // `outer / 2`.
+  const ringRadius = outer / 2;
+
+  // `react-native-svg` is required for gradients (both shapes) and for the
+  // squircle outline. A solid circle ring is a plain border and never needs it.
+  const needsSvg = wantsGradient || shape === 'squircle';
+  const svg = needsSvg ? getSvgModule() : null;
+
+  // No SVG available (or a solid circle, which never needs SVG): draw a plain
+  // bordered View. A gradient degrades to its first color; a squircle degrades
+  // to a circle border.
+  if (!svg) {
+    return (
+      <View
+        pointerEvents="none"
+        style={{
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          width: outer,
+          height: outer,
+          borderRadius: ringRadius,
+          borderColor: solidColor,
+          borderWidth: width,
+          zIndex: gap > 0 ? Z_INDEX.base : Z_INDEX.raised,
+        }}
+      />
+    );
+  }
+
+  const { default: Svg, Defs, LinearGradient, Stop, Circle, Path } = svg;
+  const stroke = wantsGradient ? `url(#${gradientId})` : solidColor;
+  const coords = gradientCoords(gradientDirection);
+  const gradientDefs = wantsGradient ? (
+    <Defs>
+      <LinearGradient id={gradientId} x1={coords.x1} y1={coords.y1} x2={coords.x2} y2={coords.y2}>
+        {colorList.map((color, index) => (
+          <Stop
+            key={`${gradientId}-${index}`}
+            offset={colorList.length === 1 ? 0 : index / (colorList.length - 1)}
+            stopColor={color}
+          />
+        ))}
+      </LinearGradient>
+    </Defs>
+  ) : null;
+
+  // The overlay fills its parent; the SVG within is sized to the ring box so a
+  // `gap === 0` ring overlays the avatar edge exactly and a `gap > 0` ring sits
+  // on the reserved outer perimeter.
+  const overlayStyle = [
+    StyleSheet.absoluteFill,
+    { zIndex: gap > 0 ? Z_INDEX.base : Z_INDEX.raised },
+  ];
+
+  if (shape === 'squircle') {
+    // The path lives in 0–1 space, so the stroke width is expressed in the same
+    // units; center-stroking it and letting the viewport clip the outer half
+    // yields a ~`width`-px band on the inner edge of the outer box.
+    return (
+      <View pointerEvents="none" style={overlayStyle}>
+        <Svg width={outer} height={outer} viewBox="0 0 1 1">
+          {gradientDefs}
+          <Path d={SQUIRCLE_PATH} fill="none" stroke={stroke} strokeWidth={(width / outer) * 2} />
+        </Svg>
+      </View>
+    );
+  }
+
+  return (
+    <View pointerEvents="none" style={overlayStyle}>
+      <Svg width={outer} height={outer} viewBox={`0 0 ${outer} ${outer}`}>
+        {gradientDefs}
+        <Circle
+          cx={outer / 2}
+          cy={outer / 2}
+          r={(outer - width) / 2}
+          fill="none"
+          stroke={stroke}
+          strokeWidth={width}
+        />
+      </Svg>
+    </View>
+  );
+};
+
+export const AvatarRing = memo(AvatarRingComponent);
+AvatarRing.displayName = 'AvatarRing';

package/src/avatar/index.ts

@@ -1,7 +1,12 @@
 export { Avatar } from './Avatar';
 export { AvatarPlaceholderProvider } from './placeholder-context';
 export type { AvatarPlaceholderConfig } from './placeholder-context';
-export type { AvatarProps, AvatarShape } from './types';
+export type {
+  AvatarProps,
+  AvatarShape,
+  AvatarRingConfig,
+  AvatarRingGradientDirection,
+} from './types';
 
 // Inlined as a base64 data URI so consumers compiling Bloom's source directly
 // do not need ambient `*.jpg` module declarations or a `.jpg` asset loader.

package/src/avatar/squircle-path.ts

@@ -0,0 +1,11 @@
+/**
+ * Squircle clip/outline path normalized to a 0–1 coordinate space
+ * (viewBox="0 0 1 1"). Shared by the squircle avatar image clip in `Avatar.tsx`
+ * and the squircle outline in `AvatarRing.tsx` so the geometry has a single
+ * source of truth.
+ */
+export const SQUIRCLE_PATH =
+  'M0 0.5 L0.00122 0.31674 L0.00489 0.25123 L0.01103 0.20331 L0.01969 0.16478 L0.03097 0.13257 L0.04495 0.10518 L0.0618 0.08177 L0.08177 0.0618 L0.10518 0.04495 L0.13257 0.03097 L0.16478 0.01969 L0.20331 0.01103 L0.25123 0.00489 L0.31674 0.00122 L0.5 0' +
+  ' L0.68895 0.0014 L0.7564 0.00561 L0.80559 0.01267 L0.84499 0.02264 L0.87771 0.03564 L0.9053 0.05181 L0.92862 0.07138 L0.94819 0.0947 L0.96436 0.12228 L0.97736 0.15501 L0.98733 0.19441 L0.99439 0.2436 L0.9986 0.31105 L1 0.5' +
+  ' L0.9986 0.68895 L0.99439 0.7564 L0.98733 0.80559 L0.97736 0.84499 L0.96436 0.87771 L0.94819 0.9053 L0.92862 0.92862 L0.9053 0.94819 L0.87771 0.96436 L0.84499 0.97736 L0.80559 0.98733 L0.7564 0.99439 L0.68895 0.9986 L0.5 1' +
+  ' L0.31105 0.9986 L0.2436 0.99439 L0.19441 0.98733 L0.15501 0.97736 L0.12228 0.96436 L0.0947 0.94819 L0.07138 0.92862 L0.05181 0.9053 L0.03564 0.87771 L0.02264 0.84499 L0.01267 0.80559 L0.00561 0.7564 L0.0014 0.68895 L0 0.5Z';

package/src/avatar/svg-module.ts

@@ -0,0 +1,11 @@
+import { lazyRequire } from '../utils/lazy-require';
+
+type SvgModuleType = typeof import('react-native-svg');
+
+/**
+ * Lazily loads `react-native-svg`, returning `null` when it is not installed
+ * (e.g. a web bundle that does not ship the optional peer). Shared by the
+ * squircle avatar image clip in `Avatar.tsx` and the `AvatarRing` so there is a
+ * single loader rather than one per call site.
+ */
+export const getSvgModule = lazyRequire<SvgModuleType>('react-native-svg');

package/src/avatar/types.ts

@@ -5,6 +5,20 @@ import type { ImageResolver } from '../image-resolver/context';
 
 export type AvatarShape = 'circle' | 'squircle';
 
+/** Gradient sweep direction for a multi-color {@link AvatarRingConfig}. */
+export type AvatarRingGradientDirection = 'diagonal' | 'horizontal' | 'vertical';
+
+export interface AvatarRingConfig {
+  /** Solid ring: one color. Gradient ring: 2+ colors. */
+  colors: string | string[];
+  /** Ring stroke width in px. Default: size > 16 ? 2 : 1. */
+  width?: number;
+  /** Gap between avatar edge and ring. Default 0 (ring overlays the edge). */
+  gap?: number;
+  /** Gradient sweep direction for multi-color rings. Default 'diagonal'. */
+  gradientDirection?: AvatarRingGradientDirection;
+}
+
 export interface AvatarProps {
   /**
    * Flexible image source — accepts a URL string, an ImageSourcePropType
@@ -70,5 +84,23 @@ export interface AvatarProps {
    * live treatments.
    */
   liveColor?: string;
+  /**
+   * Decorative ring drawn around the avatar. Pass a single color string for a
+   * solid ring, or an array of 2+ colors for a gradient ring (e.g. an
+   * Instagram-stories ring). The gradient form requires `react-native-svg`
+   * (falls back to a solid ring of the first color if it is not installed).
+   *
+   * When `gap` is 0 (default) the ring overlays the avatar edge and the
+   * component's footprint is unchanged. When `gap` > 0 the ring is drawn OUTSIDE
+   * the avatar and the rendered footprint grows to `size + 2*(width + gap)` with
+   * the avatar centered inside (matching how Instagram-stories rings sit outside
+   * the avatar).
+   *
+   * `live` is sugar over this same primitive: when set (and no explicit `ring`
+   * is passed) it renders a solid theme-`negative` ring plus the "LIVE" badge.
+   * An explicit `ring` always wins for geometry and colors; the badge stays
+   * controlled by `live`/`hideLiveBadge`.
+   */
+  ring?: AvatarRingConfig;
   testID?: string;
 }