@oxyhq/bloom 0.26.1 → 0.27.0

package/lib/typescript/commonjs/avatar/types.d.ts

@@ -1,6 +1,18 @@
 import type { ReactNode } from 'react';
 import type { ImageSourcePropType, StyleProp, ViewStyle, ImageStyle } from 'react-native';
 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
@@ -66,6 +78,24 @@ 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;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/typescript/commonjs/avatar/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/avatar/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1F,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IAC7C,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,wFAAwF;IACxF,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,sBAAsB;IACtB,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,sCAAsC;IACtC,UAAU,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACnC,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/avatar/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1F,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhD,2EAA2E;AAC3E,MAAM,MAAM,2BAA2B,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC;AAEjF,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,2BAA2B,CAAC;CACjD;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IAC7C,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,wFAAwF;IACxF,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,sBAAsB;IACtB,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,sCAAsC;IACtC,UAAU,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACnC,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/lib/typescript/module/avatar/Avatar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../../../src/avatar/Avatar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA0C,MAAM,OAAO,CAAC;AAU/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AA+a3C,eAAO,MAAM,MAAM,yCAAwB,CAAC"}
+{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../../../src/avatar/Avatar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA0C,MAAM,OAAO,CAAC;AAY/D,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,SAAS,CAAC;AA4X7D,eAAO,MAAM,MAAM,yCAAwB,CAAC"}

package/lib/typescript/module/avatar/AvatarRing.d.ts

@@ -0,0 +1,27 @@
+import React from 'react';
+import type { AvatarRingGradientDirection, AvatarShape } from './types';
+/**
+ * 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 declare function getRingOuterSize(size: number, width: number, gap: number): number;
+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;
+}
+export declare const AvatarRing: React.NamedExoticComponent<AvatarRingProps>;
+export {};
+//# sourceMappingURL=AvatarRing.d.ts.map

package/lib/typescript/module/avatar/AvatarRing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AvatarRing.d.ts","sourceRoot":"","sources":["../../../../src/avatar/AvatarRing.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAM7C,OAAO,KAAK,EAAE,2BAA2B,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAOxE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,UAAU,eAAe;IACvB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,KAAK,EAAE,WAAW,CAAC;IACnB,uDAAuD;IACvD,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,iBAAiB,EAAE,2BAA2B,CAAC;CAChD;AAmID,eAAO,MAAM,UAAU,6CAA4B,CAAC"}

package/lib/typescript/module/avatar/index.d.ts

@@ -1,7 +1,7 @@
 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';
 /** Default avatar placeholder image — use as `fallbackSource` on Avatar or in AvatarPlaceholderProvider */
 export declare const defaultAvatarSource: {
     uri: string;

package/lib/typescript/module/avatar/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/avatar/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAClE,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAMxD,2GAA2G;AAC3G,eAAO,MAAM,mBAAmB;;CAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/avatar/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAClE,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,YAAY,EACV,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,2BAA2B,GAC5B,MAAM,SAAS,CAAC;AAMjB,2GAA2G;AAC3G,eAAO,MAAM,mBAAmB;;CAAgB,CAAC"}

package/lib/typescript/module/avatar/squircle-path.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare const SQUIRCLE_PATH: string;
+//# sourceMappingURL=squircle-path.d.ts.map

package/lib/typescript/module/avatar/squircle-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"squircle-path.d.ts","sourceRoot":"","sources":["../../../../src/avatar/squircle-path.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAIyM,CAAC"}

package/lib/typescript/module/avatar/svg-module.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare const getSvgModule: () => typeof import("react-native-svg") | null;
+//# sourceMappingURL=svg-module.d.ts.map

package/lib/typescript/module/avatar/svg-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svg-module.d.ts","sourceRoot":"","sources":["../../../../src/avatar/svg-module.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,eAAO,MAAM,YAAY,gDAAiD,CAAC"}

package/lib/typescript/module/avatar/types.d.ts

@@ -1,6 +1,18 @@
 import type { ReactNode } from 'react';
 import type { ImageSourcePropType, StyleProp, ViewStyle, ImageStyle } from 'react-native';
 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
@@ -66,6 +78,24 @@ 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;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/typescript/module/avatar/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/avatar/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1F,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IAC7C,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,wFAAwF;IACxF,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,sBAAsB;IACtB,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,sCAAsC;IACtC,UAAU,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACnC,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/avatar/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1F,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhD,2EAA2E;AAC3E,MAAM,MAAM,2BAA2B,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC;AAEjF,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,2BAA2B,CAAC;CACjD;AAED,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAAC;IAC7C,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,wFAAwF;IACxF,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,sBAAsB;IACtB,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,sCAAsC;IACtC,UAAU,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACnC,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.26.1",
+  "version": "0.27.0",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -895,6 +895,7 @@
     "typescript": "tsc --noEmit",
     "pretypescript": "node scripts/generate-font-data.mjs",
     "clean": "rm -rf lib",
+    "prepack": "bun run clean && bunx bob build",
     "prepare": "bob build || true",
     "release": "rm -rf lib && bun run build && release-it",
     "storybook": "storybook dev -p 6006 --no-open",

package/src/avatar/Avatar.stories.tsx

@@ -19,6 +19,7 @@ const meta: Meta<typeof Avatar> = {
     verified: { control: 'boolean' },
     live: { control: 'boolean' },
     hideLiveBadge: { control: 'boolean' },
+    ring: { control: 'object' },
   },
 };
 
@@ -29,6 +30,13 @@ type Story = StoryObj<typeof Avatar>;
 const SAMPLE_URI =
   'https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=200&h=200&fit=crop';
 
+// Sample Instagram-stories-style gradient, defined locally in the story only —
+// Bloom ships no such palette (it stays brand-neutral). Consumers supply their
+// own ring colors via the `ring` prop.
+const STORY_GRADIENT = ['#F58529', '#DD2A7B', '#8134AF', '#515BD4'];
+// Muted gray used by IG for an already-seen story.
+const SEEN_GRAY = '#C7C7CC';
+
 export const Basic: Story = {
   args: { size: 64, name: 'Nate Isern' },
 };
@@ -118,3 +126,90 @@ export const LiveGallery: Story = {
   ),
   name: 'Live (gallery)',
 };
+
+export const GradientRing: Story = {
+  args: {
+    size: 72,
+    uri: SAMPLE_URI,
+    ring: { colors: STORY_GRADIENT, width: 3, gap: 3 },
+  },
+  name: 'Gradient ring (stories)',
+};
+
+export const SeenVsUnseen: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 20, alignItems: 'center' }}>
+      {/* Unseen → gradient ring. */}
+      <Avatar
+        size={72}
+        uri={SAMPLE_URI}
+        ring={{ colors: STORY_GRADIENT, width: 3, gap: 3 }}
+      />
+      {/* Seen → muted solid gray ring. */}
+      <Avatar
+        size={72}
+        uri={SAMPLE_URI}
+        ring={{ colors: SEEN_GRAY, width: 3, gap: 3 }}
+      />
+    </View>
+  ),
+  name: 'Seen vs unseen',
+};
+
+export const RingWithGap: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 24, alignItems: 'center' }}>
+      {/* gap 0 → overlays the edge, footprint unchanged. */}
+      <Avatar size={72} uri={SAMPLE_URI} ring={{ colors: STORY_GRADIENT, width: 3, gap: 0 }} />
+      {/* gap 4 → sits outside the avatar, footprint grows. */}
+      <Avatar size={72} uri={SAMPLE_URI} ring={{ colors: STORY_GRADIENT, width: 3, gap: 4 }} />
+      {/* gap 8 → wider clearance. */}
+      <Avatar size={72} uri={SAMPLE_URI} ring={{ colors: STORY_GRADIENT, width: 4, gap: 8 }} />
+    </View>
+  ),
+  name: 'Ring with gap',
+};
+
+export const RingSquircle: Story = {
+  args: {
+    size: 72,
+    uri: SAMPLE_URI,
+    shape: 'squircle',
+    ring: { colors: STORY_GRADIENT, width: 3, gap: 3 },
+  },
+  name: 'Gradient ring (squircle)',
+};
+
+export const SolidRing: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 20, alignItems: 'center' }}>
+      <Avatar size={72} uri={SAMPLE_URI} ring={{ colors: '#1A73E8', width: 3 }} />
+      <Avatar size={72} uri={SAMPLE_URI} shape="squircle" ring={{ colors: '#1A73E8', width: 3 }} />
+      <Avatar size={72} uri={SAMPLE_URI} ring={{ colors: '#1A73E8', width: 3, gap: 4 }} />
+    </View>
+  ),
+  name: 'Solid ring',
+};
+
+export const GradientDirections: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 20, alignItems: 'center' }}>
+      <Avatar
+        size={72}
+        uri={SAMPLE_URI}
+        ring={{ colors: STORY_GRADIENT, width: 3, gap: 3, gradientDirection: 'diagonal' }}
+      />
+      <Avatar
+        size={72}
+        uri={SAMPLE_URI}
+        ring={{ colors: STORY_GRADIENT, width: 3, gap: 3, gradientDirection: 'horizontal' }}
+      />
+      <Avatar
+        size={72}
+        uri={SAMPLE_URI}
+        ring={{ colors: STORY_GRADIENT, width: 3, gap: 3, gradientDirection: 'vertical' }}
+      />
+    </View>
+  ),
+  name: 'Gradient directions',
+};

package/src/avatar/Avatar.tsx

@@ -5,10 +5,12 @@ import type { TextStyle } from 'react-native';
 import { useTheme } from '../theme/use-theme';
 import { useImageResolver } from '../image-resolver/context';
 import { Z_INDEX } from '../styles/z-index';
-import { lazyRequire } from '../utils/lazy-require';
 import { useAvatarPlaceholder } from './placeholder-context';
 import { LiveBadge } from './LiveBadge';
-import type { AvatarProps } from './types';
+import { AvatarRing, getRingOuterSize } from './AvatarRing';
+import { getSvgModule } from './svg-module';
+import { SQUIRCLE_PATH } from './squircle-path';
+import type { AvatarProps, AvatarRingConfig } from './types';
 
 // Google Contacts-inspired palette used to pick a deterministic background
 // color for name-based placeholder avatars.
@@ -40,32 +42,8 @@ function getNameColor(name: string): string {
 // consumers compiling Bloom's source files directly.
 import DEFAULT_AVATAR_IMAGE from './default-avatar';
 
-// Squircle clip path normalized to 0–1 coordinate space (viewBox="0 0 1 1").
-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';
-
 let clipIdCounter = 0;
 
-// Lazy-loaded SVG components for squircle shape.
-// Returns null if react-native-svg is not installed.
-type SvgModuleType = typeof import('react-native-svg');
-const getSvgModule = lazyRequire<SvgModuleType>('react-native-svg');
-
-/**
- * Live-ring drawing config passed down to shape renderers.
- * - `color`: resolved ring color (theme `negative` or `liveColor` override).
- * - `strokeWidth`: stroke width in the squircle's 0–1 path coordinate space.
- * - `borderWidth`: ring border width in pixels for the circle fallback.
- */
-interface LiveRingConfig {
-  color: string;
-  strokeWidth: number;
-  borderWidth: number;
-}
-
 function SquircleImage({
   uri,
   fallbackSource,
@@ -74,7 +52,6 @@ function SquircleImage({
   placeholderIcon,
   name,
   onError,
-  liveRing,
 }: {
   uri?: string;
   fallbackSource?: AvatarProps['fallbackSource'];
@@ -83,34 +60,23 @@ function SquircleImage({
   placeholderIcon?: React.ReactNode;
   name?: string;
   onError: () => void;
-  liveRing?: LiveRingConfig;
 }) {
+  const clipId = useMemo(() => `bloom-sqc${clipIdCounter++}`, []);
   const svg = getSvgModule();
   if (!svg) {
-    // Fallback to circle if react-native-svg is not installed. The circle
-    // fallback also gets a circle live ring (matching its rendered shape).
+    // Fallback to a circle if react-native-svg is not installed. The ring (if
+    // any) is drawn separately by AvatarRing, which also degrades to a circle.
     return (
-      <>
-        <CircleFallback size={size} fallbackColor={fallbackColor} icon={placeholderIcon} name={name} />
-        {liveRing && (
-          <CircleLiveRing radius={size / 2} color={liveRing.color} borderWidth={liveRing.borderWidth} />
-        )}
-      </>
+      <CircleFallback size={size} fallbackColor={fallbackColor} icon={placeholderIcon} name={name} />
     );
   }
 
   const { default: Svg, Defs, ClipPath, Path, Image: SvgImage } = svg;
-  const clipId = useMemo(() => `bloom-sqc${clipIdCounter++}`, []);
 
   const href = uri ? { uri } : fallbackSource;
   if (!href) {
     return (
-      <>
-        <CircleFallback size={size} fallbackColor={fallbackColor} icon={placeholderIcon} name={name} />
-        {liveRing && (
-          <CircleLiveRing radius={size / 2} color={liveRing.color} borderWidth={liveRing.borderWidth} />
-        )}
-      </>
+      <CircleFallback size={size} fallbackColor={fallbackColor} icon={placeholderIcon} name={name} />
     );
   }
 
@@ -137,18 +103,6 @@ function SquircleImage({
           preserveAspectRatio="xMidYMid slice"
           clipPath={`url(#${clipId})`}
         />
-        {/* Live ring: the squircle outline stroked in the ring color. The
-            path lives in 0–1 space, so the stroke width is expressed in the
-            same units; the outer half is clipped by the SVG viewport, leaving
-            a ~borderWidth-px inset ring on the squircle edge. */}
-        {liveRing && (
-          <Path
-            d={SQUIRCLE_PATH}
-            fill="none"
-            stroke={liveRing.color}
-            strokeWidth={liveRing.strokeWidth}
-          />
-        )}
       </Svg>
     </>
   );
@@ -208,37 +162,6 @@ function CircleFallback({
   );
 }
 
-/**
- * Solid live ring for circular avatars — an absolutely-positioned inset-0
- * overlay whose border overlays the avatar edge (drawn on top of the image,
- * never a border on the image itself). Also used as the fallback ring for a
- * squircle avatar when react-native-svg is unavailable.
- */
-function CircleLiveRing({
-  radius,
-  color,
-  borderWidth,
-}: {
-  radius: number;
-  color: string;
-  borderWidth: number;
-}) {
-  return (
-    <View
-      style={[
-        StyleSheet.absoluteFill,
-        {
-          borderRadius: radius,
-          borderColor: color,
-          borderWidth,
-          zIndex: Z_INDEX.raised,
-          pointerEvents: 'none',
-        },
-      ]}
-    />
-  );
-}
-
 const AvatarComponent: React.FC<AvatarProps> = ({
   source,
   uri,
@@ -258,6 +181,7 @@ const AvatarComponent: React.FC<AvatarProps> = ({
   hideLiveBadge = false,
   liveLabel = 'LIVE',
   liveColor,
+  ring,
   testID,
 }) => {
   const [errored, setErrored] = useState(false);
@@ -323,25 +247,40 @@ const AvatarComponent: React.FC<AvatarProps> = ({
     return fallbackSource;
   }, [effectiveUri, resolvedImageSource, fallbackSource]);
 
-  // Live indicator (modeled on Bluesky): a solid ring around the avatar plus,
-  // unless suppressed, a "LIVE" pill hanging off the bottom-center. Colors come
-  // from the theme (`negative` / `negativeForeground`) with an optional
-  // `liveColor` override. The badge is only shown for `size > 16`.
-  const liveRingColor = liveColor ?? theme.colors.negative;
-  const liveBorderWidth = size > 16 ? 2 : 1;
-  const liveRing: LiveRingConfig | undefined = live
-    ? {
-        color: liveRingColor,
-        // The squircle path is in 0–1 space; center-stroking it and letting the
-        // viewport clip the outer half yields a ~`liveBorderWidth`-px inset ring.
-        strokeWidth: (liveBorderWidth / size) * 2,
-        borderWidth: liveBorderWidth,
-      }
-    : undefined;
+  // Resolve a SINGLE ring config shared by `live` and the public `ring` prop.
+  // An explicit `ring` wins for geometry and colors; otherwise `live` derives a
+  // solid theme-`negative` ring (modeled on Bluesky's live indicator). The
+  // "LIVE" badge stays independently controlled by `live` / `hideLiveBadge` and
+  // uses the theme `negative` color regardless of the ring's colors.
+  const liveBadgeColor = liveColor ?? theme.colors.negative;
+  const resolvedRing: AvatarRingConfig | undefined = ring
+    ? ring
+    : live
+      ? { colors: liveBadgeColor, width: size > 16 ? 2 : 1, gap: 0 }
+      : undefined;
+  const ringWidth = resolvedRing?.width ?? (size > 16 ? 2 : 1);
+  const ringGap = resolvedRing?.gap ?? 0;
+  // When gap > 0 the ring sits outside the avatar and the footprint grows so the
+  // avatar can be centered inside; gap 0 overlays the edge (footprint unchanged).
+  const outer = resolvedRing ? getRingOuterSize(size, ringWidth, ringGap) : size;
   const showLiveBadge = live && size > 16 && !hideLiveBadge;
 
-  const content = (
-    <View style={[styles.container, { width: size, height: size }, style]} testID={testID}>
+  const ringElement = resolvedRing ? (
+    <AvatarRing
+      size={size}
+      shape={shape}
+      colors={resolvedRing.colors}
+      width={ringWidth}
+      gap={ringGap}
+      gradientDirection={resolvedRing.gradientDirection ?? 'diagonal'}
+    />
+  ) : null;
+
+  // The avatar box holds the image and the badges (which hug the avatar). When
+  // gap > 0 this box is centered inside the larger container; when gap is 0 it
+  // fills the container exactly.
+  const avatarBox = (
+    <View style={[styles.avatarBox, { width: size, height: size }]}>
       {shape === 'squircle' ? (
         <SquircleImage
           uri={effectiveUri}
@@ -351,7 +290,6 @@ const AvatarComponent: React.FC<AvatarProps> = ({
           placeholderIcon={resolvedPlaceholderIcon}
           name={name}
           onError={() => setErrored(true)}
-          liveRing={liveRing}
         />
       ) : (
         <View style={[styles.imageContainer, { width: size, height: size, borderRadius: radius }]}>
@@ -373,11 +311,9 @@ const AvatarComponent: React.FC<AvatarProps> = ({
         </View>
       )}
 
-      {/* Circle live ring — overlays the avatar edge. The squircle shape draws
-          its own ring inside SquircleImage (SVG path or circle fallback). */}
-      {live && shape !== 'squircle' && (
-        <CircleLiveRing radius={radius} color={liveRingColor} borderWidth={liveBorderWidth} />
-      )}
+      {/* Overlay ring (gap 0) overlays the avatar edge, above the image but
+          below the badges. */}
+      {ringGap === 0 ? ringElement : null}
 
       {verified && verifiedIcon && (
         <View
@@ -397,13 +333,22 @@ const AvatarComponent: React.FC<AvatarProps> = ({
         <LiveBadge
           variant={size > 32 ? 'small' : 'tiny'}
           label={liveLabel}
-          backgroundColor={liveRingColor}
+          backgroundColor={liveBadgeColor}
           textColor={theme.colors.negativeForeground}
         />
       )}
     </View>
   );
 
+  const content = (
+    <View style={[styles.container, { width: outer, height: outer }, style]} testID={testID}>
+      {/* Outside ring (gap > 0) sits on the reserved perimeter, behind the
+          avatar box so the avatar and its badges paint on top. */}
+      {ringGap > 0 ? ringElement : null}
+      {avatarBox}
+    </View>
+  );
+
   if (onPress) {
     return <TouchableOpacity onPress={onPress}>{content}</TouchableOpacity>;
   }
@@ -418,6 +363,12 @@ const styles = StyleSheet.create({
     justifyContent: 'center',
     alignItems: 'center',
   },
+  avatarBox: {
+    position: 'relative',
+    overflow: 'visible',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
   imageContainer: {
     overflow: 'hidden',
     justifyContent: 'center',