@oxyhq/bloom 1.12.0 → 1.14.0

package/lib/typescript/module/layout/bottom-edge.d.ts

@@ -27,32 +27,27 @@
  * edge, so two surfaces at that edge overlap rather than stack; the tallest is
  * what a new surface has to clear. Summing would strand it at twice the height.
  *
- * ## A size and a state, because they travel differently
- *
- * A surface that collapses — the tab bar minimizes 58 -> 44 on scroll — publishes
- * two things, and only one of them is a measurement:
- *
- *   - RESERVED (`useBottomEdgeInset`) never shrinks while the claimant is
- *     mounted. It is what must be kept permanently free: a list's bottom
- *     padding, a toast stack's offset. Shrinking it on collapse would jitter a
- *     list's content size on every scroll and jump a toast 14px mid-display,
- *     because the bar re-expands the instant the user scrolls back up.
- *   - COLLAPSED (`useBottomEdgeCollapsed`) is a boolean, deliberately, and this
- *     is the part that was learned the hard way. It first shipped as a live
- *     PIXEL height so a FAB could ride down with the bar — and it felt broken on
- *     a device. The bar animates on the UI thread; a React consumer learns about
- *     the change through `runOnJS` plus two render passes, so its motion STARTS
- *     one to three frames late, worst exactly while scrolling because that is
- *     when the JS thread is busiest. No spring config fixes a variable start
- *     delay.
- *
- * Two things moving together betray that lag; a state change does not. A reader
- * that FADES on this boolean has no spatial relationship to violate, so the same
- * few frames of latency are imperceptible. That is why the channel is a state and
- * not a geometry: it is the shape of signal that survives the trip to the JS
- * thread. Anything that genuinely must track the collapse per-frame has to read
- * the tab bar's own shared value on the UI thread instead — React state is the
- * wrong transport for it, at any width.
+ * ## What does NOT belong here: the collapse
+ *
+ * The tab bar minimizes 58 -> 44 on scroll, and this registry twice tried to
+ * publish that so a FAB could react — first as a live pixel height (1.11.0), then
+ * as a boolean (1.12.0). Both felt wrong on a device, for the same reason, and
+ * the reason is structural rather than a matter of tuning:
+ *
+ *   the bar animates on the UI thread, while anything reading it from here
+ *   arrives via `runOnJS` plus two React render passes.
+ *
+ * So a consumer's reaction STARTS one to three frames after the bar's, and the
+ * delay is variable — worst exactly while scrolling, because that is when the JS
+ * thread is busiest. Fading instead of moving does not hide it either: the eye
+ * still sees two pieces of chrome change at different moments.
+ *
+ * A collapse is MOTION, and motion that must stay in lock-step with a
+ * reanimated animation has to travel as a shared value on the UI thread. React
+ * state is the wrong transport at any width, so it is not offered here at all.
+ * The app owns that signal — Mention drives its header, its bar and its FAB from
+ * one `SharedValue` through `useAnimatedStyle` — and this registry stays what it
+ * is good at: GEOMETRY. Where things are, not when they move.
  *
  * ## Why an external store
  *
@@ -74,15 +69,13 @@ export declare namespace BottomEdgeProvider {
     var displayName: string;
 }
 /**
- * How much of the bottom edge is permanently RESERVED, in px.
+ * How much of the bottom edge is already occupied, in px.
  *
- * Never shrinks while its claimant is mounted, so it is the number for anything
- * that must not move as the user scrolls — a list's bottom padding, a toast
- * stack's offset:
+ * Add it to whatever offset the surface would otherwise use:
  *
  * ```tsx
- * const reserved = useBottomEdgeInset();
- * <FlatList contentContainerStyle={{ paddingBottom: reserved + 12 }} />
+ * const occupied = useBottomEdgeInset();
+ * <View style={{ position: 'absolute', bottom: windowEdgeGap(insets.bottom) + occupied }} />
  * ```
  *
  * `0` outside a provider, and `0` on the first commit even inside one — a claim
@@ -92,34 +85,15 @@ export declare namespace BottomEdgeProvider {
  */
 export declare function useBottomEdgeInset(): number;
 /**
- * Whether the surface owning the bottom edge is currently COLLAPSED — the tab
- * bar minimized on scroll.
- *
- * A boolean rather than a live height, on purpose: see the note at the top of
- * this file. A reader should FADE or otherwise change state on it, never try to
- * stay geometrically locked to the collapsing surface — that lock is what a
- * React-state channel cannot deliver, because the surface animates on the UI
- * thread and this arrives one to three frames later.
- *
- * ```tsx
- * const collapsed = useBottomEdgeCollapsed();
- * // fade out; do not chase the bar's new top edge
- * ```
- *
- * `false` outside a provider.
- */
-export declare function useBottomEdgeCollapsed(): boolean;
-/**
- * Claim the bottom edge for as long as the caller is mounted.
+ * Claim `height` px of the bottom edge for as long as the caller is mounted.
  *
  * The claimant owns its own placement — claiming does not move it. It declares
- * the space it occupies so that everything reading the edge stays off it. Pass
- * the FULL footprint (the surface's height plus the gap it holds off the window
- * edge), which is the same number the surface positions itself with, and keep it
- * at the surface's FULL size even while collapsed: `reserved` is what must stay
- * permanently free, and the collapse is reported separately by `collapsed`.
+ * the space it occupies so that everything reading `useBottomEdgeInset()` stays
+ * off it. Pass the FULL footprint (the surface's height plus the gap it holds
+ * off the window edge), which is the same number the surface positions itself
+ * with.
  *
  * A no-op outside a provider, so a surface stays usable standalone.
  */
-export declare function useClaimBottomEdge(reserved: number, collapsed?: boolean): void;
+export declare function useClaimBottomEdge(height: number): void;
 //# sourceMappingURL=bottom-edge.d.ts.map

package/lib/typescript/module/layout/bottom-edge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bottom-edge.d.ts","sourceRoot":"","sources":["../../../../src/layout/bottom-edge.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,OAAO,EAOL,KAAK,iBAAiB,EACvB,MAAM,OAAO,CAAC;AAyEf;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,EAAE,iBAAiB,2CAGjE;yBAHe,kBAAkB;;;AAalC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAOhD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,IAAI,CAS5E"}
+{"version":3,"file":"bottom-edge.d.ts","sourceRoot":"","sources":["../../../../src/layout/bottom-edge.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,OAAO,EAOL,KAAK,iBAAiB,EACvB,MAAM,OAAO,CAAC;AAsDf;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,EAAE,iBAAiB,2CAGjE;yBAHe,kBAAkB;;;AAYlC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CASvD"}

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

@@ -5,5 +5,5 @@
  * parked there". A surface that floats at the bottom needs both.
  */
 export { EDGE_GAP, windowEdgeGap } from './edge';
-export { BottomEdgeProvider, useBottomEdgeInset, useBottomEdgeCollapsed, useClaimBottomEdge, } from './bottom-edge';
+export { BottomEdgeProvider, useBottomEdgeInset, useClaimBottomEdge } from './bottom-edge';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/layout/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/layout/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/lib/typescript/module/tab-bar/TabBarBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TabBarBase.d.ts","sourceRoot":"","sources":["../../../../src/tab-bar/TabBarBase.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAQL,KAAK,aAAa,EACnB,MAAM,OAAO,CAAC;AAoBf,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,OAAO,EAiBL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAe,MAAM,SAAS,CAAC;AA2kB3E;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,EAC1C,IAAI,EAAE,aAAa,CAAC,oBAAoB,CAAC;YAElB,WAAW;;EAGnC;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC;YAC1C,iBAAiB;;EAG/C"}
+{"version":3,"file":"TabBarBase.d.ts","sourceRoot":"","sources":["../../../../src/tab-bar/TabBarBase.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,OAAO,CAAC;AAoBf,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,OAAO,EAiBL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAe,MAAM,SAAS,CAAC;AAinB3E;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,aAAa,CAAC,kBAAkB,CAAC,EAC1C,IAAI,EAAE,aAAa,CAAC,oBAAoB,CAAC;YAElB,WAAW;;EAGnC;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,gBAAgB,CAAC;YAC1C,iBAAiB;;EAG/C"}

package/lib/typescript/module/tab-bar/expo-router/RouterTabBar.d.ts

@@ -16,6 +16,11 @@ import type { TabBarItem, TabBarProps } from '../types';
  * by each trigger's own focus (see `RouterTabBarButton`), which is what keeps it
  * correct through deep links, back gestures and any other programmatic
  * navigation. Setting both would put two writers on one shared value.
+ *
+ * `activeProgress` is NOT omitted, and that is not an oversight. It answers a
+ * different question — where the highlight is, not whether there is one — so a
+ * router-focused bar whose screens are PAGED can pass it and keep the focus
+ * path for selection. See `TabBarProps.activeProgress`.
  */
 export type RouterTabBarProps = TabListProps & Omit<TabBarProps, 'activeIndex'>;
 export type RouterTabBarButtonProps = TabTriggerSlotProps & {

package/lib/typescript/module/tab-bar/expo-router/RouterTabBar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RouterTabBar.d.ts","sourceRoot":"","sources":["../../../../../src/tab-bar/expo-router/RouterTabBar.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;AAEhF,MAAM,MAAM,uBAAuB,GAAG,mBAAmB,GAAG;IAC1D,IAAI,EAAE,UAAU,CAAC;IACjB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,EAI3B,OAAO,EAAE,QAAQ,EACjB,GAAG,KAAK,EACT,EAAE,iBAAiB,2CAEnB;yBARe,YAAY;;;AAY5B;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EACJ,KAAK,EAIL,IAAI,EAAE,KAAK,EACX,GAAG,KAAK,EACT,EAAE,uBAAuB,2CAEzB;yBAVe,kBAAkB"}
+{"version":3,"file":"RouterTabBar.d.ts","sourceRoot":"","sources":["../../../../../src/tab-bar/expo-router/RouterTabBar.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;AAEhF,MAAM,MAAM,uBAAuB,GAAG,mBAAmB,GAAG;IAC1D,IAAI,EAAE,UAAU,CAAC;IACjB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,EAI3B,OAAO,EAAE,QAAQ,EACjB,GAAG,KAAK,EACT,EAAE,iBAAiB,2CAEnB;yBARe,YAAY;;;AAY5B;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EACJ,KAAK,EAIL,IAAI,EAAE,KAAK,EACX,GAAG,KAAK,EACT,EAAE,uBAAuB,2CAEzB;yBAVe,kBAAkB"}

package/lib/typescript/module/tab-bar/types.d.ts

@@ -4,14 +4,21 @@
  *
  * Public API types for `@oxyhq/bloom/tab-bar`.
  *
- * This module imports from `react` and `react-native` ONLY. It is resolved by a
- * consumer's `tsc`, by Metro, and by every web bundler alike, so a platform
- * import here (expo-glass-effect / expo-symbols / expo-router) would break all
- * three at once. Platform behaviour lives in `surface.native.tsx` /
- * `glyph.native.tsx` / `surface.web.tsx` and the `expo-router/` adapter.
+ * This module names no PLATFORM package. It is resolved by a consumer's `tsc`,
+ * by Metro, and by every web bundler alike, so an import here of
+ * expo-glass-effect / expo-symbols / expo-router / react-native-screens would
+ * break all three at once. Platform behaviour lives in `surface.native.tsx` /
+ * `glyph.native.tsx` / `surface.web.tsx` and the `expo-router/` adapter; the
+ * gate is `src/__tests__/TabBarWebFork.test.ts`.
+ *
+ * `react-native-reanimated` is exempt and always was: it is a REQUIRED peer that
+ * every neutral module in this family already imports at runtime
+ * (`TabBarBase.tsx`), and the one reference below is `import type`, erased
+ * before any bundler sees it.
  */
 import type { ReactNode } from 'react';
 import type { PressableProps, ViewProps } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
 export type TabBarItem = {
     /** Stable identity for the tab (a route name in router-driven usage). */
     name: string;
@@ -89,6 +96,30 @@ export type TabBarProps = ViewProps & {
      * highlight from its own `isFocused`.
      */
     activeIndex?: number;
+    /**
+     * DRIVEN path — the highlight's live position, in TAB UNITS, on the UI thread.
+     * A pager writes its own page position here (`1.4` is 40% of the way from the
+     * second tab to the third) and the highlight tracks the finger 1:1 instead of
+     * springing to a settled index after the navigation commits.
+     *
+     * It says WHERE the highlight is, never WHETHER there is one. Selection stays
+     * with the path already in play: `activeIndex` when the bar is controlled (an
+     * index naming no tab still fades the highlight out — see above), each
+     * button's `isFocused` when it is not. Passing this alone, with neither, is a
+     * bar that is always selected, which is what the focus-driven path already
+     * means.
+     *
+     * PRECEDENCE, because a shared value with two writers is a race: the SCRUB
+     * always wins — a finger on the bar is a direct manipulation of the bar, and
+     * releasing it reports through `onIndexChange` like any other selection. Below
+     * that, this value wins over every discrete writer: while it is supplied, the
+     * controlled effect, the focus effect and a `TabBarButton`'s own press all
+     * stop writing the position and leave it to the driver. So a consumer that
+     * passes this must keep it truthful — spring it to the settled index after a
+     * commit, and after any navigation it did not cause (a deep link, a back
+     * gesture), or the highlight stays where the last gesture left it.
+     */
+    activeProgress?: SharedValue<number>;
     /**
      * Called with the chosen index when a tab is picked by tap, by scrub release,
      * or by keyboard/assistive-technology activation of a `TabBarButton`.

package/lib/typescript/module/tab-bar/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/tab-bar/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9D,MAAM,MAAM,UAAU,GAAG;IACvB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;OAUG;IACH,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG;IACpC;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAC/C,IAAI,EAAE,UAAU,CAAC;IACjB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/tab-bar/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D,MAAM,MAAM,UAAU,GAAG;IACvB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;OAUG;IACH,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG;IACpC;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAC/C,IAAI,EAAE,UAAU,CAAC;IACjB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "packageManager": "bun@1.3.14",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",

package/src/avatar/Avatar.tsx

@@ -10,8 +10,8 @@ import { Z_INDEX } from '../styles/z-index';
 import { useAvatarPlaceholder } from './context';
 import { LiveBadge } from './LiveBadge';
 import { AvatarRing, getRingOuterSize } from './AvatarRing';
-import { SQUIRCLE_PATH } from './squircle-path';
-import type { AvatarProps, AvatarRingConfig } from './types';
+import { resolveAvatarShape } from './resolve-shape';
+import type { AvatarProps, AvatarRingConfig, AvatarShapePath } from './types';
 
 // Google Contacts-inspired palette used to pick a deterministic background
 // color for name-based placeholder avatars.
@@ -45,10 +45,19 @@ import DEFAULT_AVATAR_IMAGE from './default-avatar';
 
 let clipIdCounter = 0;
 
-function SquircleImage({
+/**
+ * Renders the avatar image clipped to an arbitrary outline.
+ *
+ * The path and the SVG viewport share one coordinate space, so a 0–1 squircle
+ * and a 0–100 named shape both work without rewriting their numbers: the
+ * viewport is declared at the path's own scale and the whole thing is drawn at
+ * `size` pixels.
+ */
+function ClippedImage({
   uri,
   fallbackSource,
   size,
+  shape,
   fallbackColor,
   placeholderIcon,
   name,
@@ -57,6 +66,7 @@ function SquircleImage({
   uri?: string;
   fallbackSource?: AvatarProps['fallbackSource'];
   size: number;
+  shape: AvatarShapePath;
   fallbackColor: string;
   placeholderIcon?: React.ReactNode;
   name?: string;
@@ -71,6 +81,8 @@ function SquircleImage({
     );
   }
 
+  const span = shape.viewBox ?? 1;
+
   return (
     <>
       {/* Hidden RN Image for error detection on remote URIs */}
@@ -81,16 +93,16 @@ function SquircleImage({
           onError={onError}
         />
       )}
-      <Svg width={size} height={size} viewBox="0 0 1 1">
+      <Svg width={size} height={size} viewBox={`0 0 ${span} ${span}`}>
         <Defs>
           <ClipPath id={clipId}>
-            <Path d={SQUIRCLE_PATH} />
+            <Path d={shape.d} />
           </ClipPath>
         </Defs>
         <SvgImage
           href={href}
-          width={1}
-          height={1}
+          width={span}
+          height={span}
           preserveAspectRatio="xMidYMid slice"
           clipPath={`url(#${clipId})`}
         />
@@ -183,6 +195,10 @@ const AvatarComponent: React.FC<AvatarProps> = ({
   const theme = useTheme();
   const placeholderConfig = useAvatarPlaceholder();
   const radius = size / 2;
+  // `null` means "a circle", which is drawn with borderRadius and never reaches
+  // the SVG renderer. Memoised so an inline `shape={{ d: … }}` object literal
+  // does not produce a new clip descriptor on every render.
+  const clipShape = useMemo(() => resolveAvatarShape(shape), [shape]);
   const hasName = typeof name === 'string' && name.trim().length > 0;
   // Priority: explicit placeholderColor > deterministic color from name > theme default.
   const fallbackColor =
@@ -265,7 +281,7 @@ const AvatarComponent: React.FC<AvatarProps> = ({
   const ringElement = resolvedRing ? (
     <AvatarRing
       size={size}
-      shape={shape}
+      shape={clipShape}
       colors={resolvedRing.colors}
       width={ringWidth}
       gap={ringGap}
@@ -278,11 +294,12 @@ const AvatarComponent: React.FC<AvatarProps> = ({
   // fills the container exactly.
   const avatarBox = (
     <View style={[styles.avatarBox, { width: size, height: size }]}>
-      {shape === 'squircle' ? (
-        <SquircleImage
+      {clipShape ? (
+        <ClippedImage
           uri={effectiveUri}
           fallbackSource={fallbackSource}
           size={size}
+          shape={clipShape}
           fallbackColor={fallbackColor}
           placeholderIcon={resolvedPlaceholderIcon}
           name={name}

package/src/avatar/AvatarRing.tsx

@@ -3,8 +3,8 @@ import { View, StyleSheet } from 'react-native';
 import Svg, { Circle, Defs, LinearGradient, Path, Stop } from 'react-native-svg';
 
 import { Z_INDEX } from '../styles/z-index';
-import { SQUIRCLE_PATH } from './squircle-path';
-import type { AvatarRingGradientDirection, AvatarShape } from './types';
+import type { ResolvedAvatarShape } from './resolve-shape';
+import type { AvatarRingGradientDirection } from './types';
 
 // Module counter for unique gradient element ids — mirrors the `clipIdCounter`
 // pattern in `Avatar.tsx`. Deterministic (no `Math.random()`) so ids are stable
@@ -25,8 +25,8 @@ export function getRingOuterSize(size: number, width: number, gap: number): numb
 interface AvatarRingProps {
   /** Avatar diameter in px (the inner content size, before any gap). */
   size: number;
-  /** Matches the avatar shape. */
-  shape: AvatarShape;
+  /** The avatar's resolved outline, or `null` for a circle. */
+  shape: ResolvedAvatarShape;
   /** Solid ring: one color. Gradient ring: 2+ colors. */
   colors: string | string[];
   /** Ring stroke width in px. */
@@ -79,10 +79,10 @@ const AvatarRingComponent: React.FC<AvatarRingProps> = ({
   // box; drawn as a plain border it is a full circle → radius `outer / 2`.
   const ringRadius = outer / 2;
 
-  // SVG is only needed for gradients (both shapes) and for the squircle
-  // outline. A solid circle ring is a plain bordered View — cheaper, and it
-  // keeps the common case off the SVG renderer entirely.
-  const needsSvg = wantsGradient || shape === 'squircle';
+  // SVG is only needed for gradients and for non-circular outlines. A solid
+  // circle ring is a plain bordered View — cheaper, and it keeps the common
+  // case off the SVG renderer entirely.
+  const needsSvg = wantsGradient || shape !== null;
 
   if (!needsSvg) {
     return (
@@ -127,15 +127,22 @@ const AvatarRingComponent: React.FC<AvatarRingProps> = ({
     { 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.
+  if (shape !== null) {
+    // The path lives in its own square space, so the stroke width has to be
+    // expressed in those units too: one unit is `outer / span` px. Center-
+    // stroking and letting the viewport clip the outer half yields a
+    // ~`width`-px band on the inner edge of the outer box, hence the doubling.
+    const span = shape.viewBox ?? 1;
     return (
       <View pointerEvents="none" style={overlayStyle}>
-        <Svg width={outer} height={outer} viewBox="0 0 1 1">
+        <Svg width={outer} height={outer} viewBox={`0 0 ${span} ${span}`}>
           {gradientDefs}
-          <Path d={SQUIRCLE_PATH} fill="none" stroke={stroke} strokeWidth={(width / outer) * 2} />
+          <Path
+            d={shape.d}
+            fill="none"
+            stroke={stroke}
+            strokeWidth={(width / outer) * 2 * span}
+          />
         </Svg>
       </View>
     );

package/src/avatar/index.ts

@@ -4,7 +4,14 @@ export type { AvatarPlaceholderConfig } from './context';
 export type {
   AvatarProps,
   AvatarShape,
+  AvatarShapePath,
   AvatarRingConfig,
   AvatarRingGradientDirection,
 } from './types';
 export { defaultAvatarSource } from './default-avatar';
+export {
+  AVATAR_SHAPE_PATHS,
+  AVATAR_SHAPE_LABELS,
+  NAMED_SHAPE_VIEW_BOX,
+} from './shape-paths';
+export type { AvatarShapeName } from './shape-paths';

package/src/avatar/resolve-shape.ts

@@ -0,0 +1,33 @@
+import { SQUIRCLE_PATH } from './squircle-path';
+import { AVATAR_SHAPE_PATHS, NAMED_SHAPE_VIEW_BOX } from './shape-paths';
+import type { AvatarShape, AvatarShapePath } from './types';
+
+/**
+ * A shape reduced to what the renderers need: either nothing (a circle, drawn
+ * with `borderRadius` and no SVG at all) or one outline plus the size of the
+ * square space it is drawn in.
+ */
+export type ResolvedAvatarShape = AvatarShapePath | null;
+
+/**
+ * Turns the public `shape` prop into an outline.
+ *
+ * Returns `null` for a circle so callers can keep the cheap `borderRadius`
+ * path — the common case never touches `react-native-svg`. An unknown string
+ * also returns `null`: a shape name that does not resolve should degrade to a
+ * plain circular avatar, never to a blank hole where a face should be.
+ */
+export function resolveAvatarShape(shape: AvatarShape | AvatarShapePath | undefined): ResolvedAvatarShape {
+  if (!shape || shape === 'circle') return null;
+
+  if (typeof shape !== 'string') {
+    return { d: shape.d, viewBox: shape.viewBox ?? 1 };
+  }
+
+  if (shape === 'squircle') {
+    return { d: SQUIRCLE_PATH, viewBox: 1 };
+  }
+
+  const named = AVATAR_SHAPE_PATHS[shape];
+  return named ? { d: named, viewBox: NAMED_SHAPE_VIEW_BOX } : null;
+}

package/src/avatar/shape-paths.ts

@@ -0,0 +1,150 @@
+/**
+ * Named avatar outlines.
+ *
+ * Each entry is an SVG path drawn in a 100×100 square coordinate space, scaled
+ * at render time to the avatar's pixel size. That space is declared once in
+ * {@link NAMED_SHAPE_VIEW_BOX} rather than baked into the numbers, so the paths
+ * can be read and edited at human-friendly magnitudes. The built-in squircle
+ * lives in `squircle-path.ts` and uses a 0–1 space; both are supported because
+ * {@link AvatarShapePath} carries its own `viewBox`.
+ *
+ * `circle` is deliberately absent: a circular avatar is rendered with
+ * `borderRadius` and never reaches the SVG renderer.
+ */
+
+/** Side length of the coordinate space every path below is drawn in. */
+export const NAMED_SHAPE_VIEW_BOX = 100;
+
+export type AvatarShapeName =
+  | 'square' | 'slanted' | 'arch' | 'semicircle'
+  | 'oval' | 'pill' | 'triangle' | 'arrow' | 'fan'
+  | 'diamond' | 'clamshell' | 'pentagon' | 'gem' | 'very-sunny'
+  | 'sunny' | '4-sided-cookie' | '6-sided-cookie' | '7-sided-cookie'
+  | '9-sided-cookie' | '12-sided-cookie' | '4-leaf-clover'
+  | '8-leaf-clover' | 'burst' | 'soft-burst' | 'boom' | 'soft-boom'
+  | 'flower' | 'puffy' | 'puffy-diamond' | 'ghost-ish'
+  | 'pixel-circle' | 'pixel-triangle' | 'bun' | 'heart';
+
+export const AVATAR_SHAPE_PATHS: Record<AvatarShapeName, string> = {
+  // --- Basic ---
+  square:
+    'M12 0H88Q100 0 100 12V88Q100 100 88 100H12Q0 100 0 88V12Q0 0 12 0Z',
+  slanted:
+    'M22 0H88Q100 0 100 12V78Q100 100 78 100H12Q0 100 0 88V22Q0 0 22 0Z',
+  arch:
+    'M50 0Q100 0 100 50V88Q100 100 88 100H12Q0 100 0 88V50Q0 0 50 0Z',
+  semicircle:
+    'M0 50A50 50 0 0 1 100 50V88Q100 100 88 100H12Q0 100 0 88Z',
+
+  // --- Organic ---
+  oval:
+    'M50 2C78 2 96 22 96 50S78 98 50 98S4 78 4 50S22 2 50 2Z',
+  pill:
+    'M34 4H66Q96 4 96 34V66Q96 96 66 96H34Q4 96 4 66V34Q4 4 34 4Z',
+  triangle:
+    'M50 5L95 90Q97 95 92 95H8Q3 95 5 90Z',
+  arrow:
+    'M50 0L100 45Q100 52 94 52H68V92Q68 100 58 100H42Q32 100 32 92V52H6Q0 52 0 45Z',
+  fan:
+    'M50 8Q90 8 96 48Q100 78 70 96Q50 108 30 96Q0 78 4 48Q10 8 50 8Z',
+
+  // --- Geometric ---
+  diamond:
+    'M50 2L96 50L50 98L4 50Z',
+  clamshell:
+    'M10 20Q10 4 26 4H74Q90 4 90 20V60Q90 96 50 96Q10 96 10 60Z',
+  pentagon:
+    'M50 2L97 36L79 96H21L3 36Z',
+  gem:
+    'M30 4H70L98 36L50 98L2 36Z',
+
+  // --- Sunny/Cookie ---
+  'very-sunny':
+    'M50 0L58 20L78 6L72 28L96 22L82 42L100 50L82 58L96 78L72 72L78 94L58 80L50 100L42 80L22 94L28 72L4 78L18 58L0 50L18 42L4 22L28 28L22 6L42 20Z',
+  sunny:
+    'M50 4L60 24L80 10L74 32L98 28L84 48L100 50L84 52L98 72L74 68L80 90L60 76L50 96L40 76L20 90L26 68L2 72L16 52L0 50L16 48L2 28L26 32L20 10L40 24Z',
+  '4-sided-cookie':
+    'M50 2Q76 22 76 50Q76 78 50 98Q24 78 24 50Q24 22 50 2Z',
+  '6-sided-cookie':
+    'M50 2Q72 10 82 30Q92 52 80 74Q66 96 44 96Q22 96 10 74Q-2 52 10 30Q22 10 50 2Z',
+  '7-sided-cookie':
+    'M50 2Q70 6 84 22Q96 40 94 62Q90 82 74 94Q56 102 38 96Q20 88 10 70Q2 50 8 32Q18 10 50 2Z',
+  '9-sided-cookie':
+    'M50 2Q64 4 76 14Q86 26 92 42Q94 58 88 72Q78 86 64 94Q50 98 36 94Q22 86 12 72Q6 58 8 42Q14 26 24 14Q36 4 50 2Z',
+  '12-sided-cookie':
+    'M50 2L62 6L74 14L84 26L90 40L92 54L88 68L80 80L68 88L54 92L40 90L28 84L18 72L10 58L8 44L12 30L20 18L32 10L44 4Z',
+
+  // --- Nature ---
+  '4-leaf-clover':
+    'M50 4Q70 4 70 26Q96 26 96 50Q96 74 70 74Q70 96 50 96Q30 96 30 74Q4 74 4 50Q4 26 30 26Q30 4 50 4Z',
+  '8-leaf-clover':
+    'M50 2Q60 16 72 8Q84 16 80 30Q96 32 92 46Q100 60 86 66Q92 80 78 84Q76 98 60 92Q52 100 42 92Q28 98 24 84Q10 80 16 66Q2 60 10 46Q6 32 22 30Q18 16 30 8Q42 16 50 2Z',
+  burst:
+    'M50 0L56 30L80 6L62 34L100 26L70 44L100 50L70 56L100 74L62 66L80 94L56 70L50 100L44 70L20 94L38 66L0 74L30 56L0 50L30 44L0 26L38 34L20 6L44 30Z',
+  'soft-burst':
+    'M50 4L58 28L78 8L66 32L96 24L76 44L98 50L76 56L96 76L66 68L78 92L58 72L50 96L42 72L22 92L34 68L4 76L24 56L2 50L24 44L4 24L34 32L22 8L42 28Z',
+  boom:
+    'M50 0L54 18L62 2L60 20L76 6L68 24L88 14L76 30L98 24L82 38L100 38L86 46L100 50L86 54L100 62L82 62L98 76L76 70L88 86L68 76L76 94L60 80L62 98L54 82L50 100L46 82L38 98L40 80L24 94L32 76L12 86L24 70L2 76L18 62L0 62L14 54L0 50L14 46L0 38L18 38L2 24L24 30L12 14L32 24L24 6L40 20L38 2L46 18Z',
+  'soft-boom':
+    'M50 4L56 22L68 6L64 26L82 14L74 32L94 24L82 40L100 36L86 48L100 50L86 52L100 64L82 60L94 76L74 68L82 86L64 74L68 94L56 78L50 96L44 78L32 94L36 74L18 86L26 68L6 76L18 60L0 64L14 52L0 50L14 48L0 36L18 40L6 24L26 32L18 14L36 26L32 6L44 22Z',
+  flower:
+    'M50 4Q62 18 72 10Q82 18 76 32Q90 30 88 44Q98 50 88 56Q90 70 76 68Q82 82 72 90Q62 82 50 96Q38 82 28 90Q18 82 24 68Q10 70 12 56Q2 50 12 44Q10 30 24 32Q18 18 28 10Q38 18 50 4Z',
+  puffy:
+    'M34 6Q50-4 66 6Q84 6 90 22Q104 34 96 50Q104 66 90 78Q84 94 66 94Q50 104 34 94Q16 94 10 78Q-4 66 4 50Q-4 34 10 22Q16 6 34 6Z',
+  'puffy-diamond':
+    'M50 2Q66 10 72 4Q86 12 84 28Q98 32 94 48Q100 64 86 70Q88 86 72 88Q62 98 48 94Q34 100 26 86Q12 88 8 72Q-2 62 6 48Q0 32 16 28Q14 12 28 4Q38 10 50 2Z',
+
+  // --- Fun ---
+  'ghost-ish':
+    'M20 96V40Q20 4 50 4Q80 4 80 40V96L70 86L60 96L50 86L40 96L30 86Z',
+  'pixel-circle':
+    'M30 4H70V4H86V14H96V30H100V70H96V86H86V96H70V100H30V96H14V86H4V70H0V30H4V14H14V4H30Z',
+  'pixel-triangle':
+    'M42 4H58V18H70V32H82V46H94V60H100V100H0V60H6V46H18V32H30V18H42Z',
+  bun:
+    'M12 54Q-4 24 20 8Q44-6 68 8Q92 22 94 50Q96 72 76 88Q56 100 36 96Q14 90 12 54Z',
+  heart:
+    'M50 90C25 70 2 55 2 32Q2 10 24 6Q40 2 50 18Q60 2 76 6Q98 10 98 32Q98 55 75 70Z',
+};
+
+/**
+ * Display labels for the named shapes, in the order a picker should show them.
+ * Exported so consumers building a shape picker do not re-derive the order (or
+ * the capitalisation) themselves.
+ */
+export const AVATAR_SHAPE_LABELS: { name: AvatarShapeName; label: string }[] = [
+  { name: 'square', label: 'Square' },
+  { name: 'slanted', label: 'Slanted' },
+  { name: 'arch', label: 'Arch' },
+  { name: 'semicircle', label: 'Semicircle' },
+  { name: 'oval', label: 'Oval' },
+  { name: 'pill', label: 'Pill' },
+  { name: 'triangle', label: 'Triangle' },
+  { name: 'arrow', label: 'Arrow' },
+  { name: 'fan', label: 'Fan' },
+  { name: 'diamond', label: 'Diamond' },
+  { name: 'clamshell', label: 'Clamshell' },
+  { name: 'pentagon', label: 'Pentagon' },
+  { name: 'gem', label: 'Gem' },
+  { name: 'very-sunny', label: 'Very Sunny' },
+  { name: 'sunny', label: 'Sunny' },
+  { name: '4-sided-cookie', label: '4-Sided Cookie' },
+  { name: '6-sided-cookie', label: '6-Sided Cookie' },
+  { name: '7-sided-cookie', label: '7-Sided Cookie' },
+  { name: '9-sided-cookie', label: '9-Sided Cookie' },
+  { name: '12-sided-cookie', label: '12-Sided Cookie' },
+  { name: '4-leaf-clover', label: '4-Leaf Clover' },
+  { name: '8-leaf-clover', label: '8-Leaf Clover' },
+  { name: 'burst', label: 'Burst' },
+  { name: 'soft-burst', label: 'Soft Burst' },
+  { name: 'boom', label: 'Boom' },
+  { name: 'soft-boom', label: 'Soft Boom' },
+  { name: 'flower', label: 'Flower' },
+  { name: 'puffy', label: 'Puffy' },
+  { name: 'puffy-diamond', label: 'Puffy Diamond' },
+  { name: 'ghost-ish', label: 'Ghost-ish' },
+  { name: 'pixel-circle', label: 'Pixel Circle' },
+  { name: 'pixel-triangle', label: 'Pixel Triangle' },
+  { name: 'bun', label: 'Bun' },
+  { name: 'heart', label: 'Heart' },
+];