@oxyhq/bloom 0.26.1 → 0.28.0

package/src/hooks/useGutters.ts

@@ -0,0 +1,99 @@
+import { useMemo } from 'react';
+import { useWindowDimensions } from 'react-native';
+
+import { BREAKPOINTS } from '../styles/breakpoints';
+import { space } from '../styles/tokens';
+
+/**
+ * A named gutter size, or `0` for no padding on that edge.
+ *
+ * - `'compact'` — tight gutter (dense lists, chips).
+ * - `'base'` — the default page gutter.
+ * - `'wide'` — roomy gutter (marketing / hero surfaces).
+ */
+export type Gutter = 'compact' | 'base' | 'wide' | 0;
+
+/** Resolved edge padding in px — one value per side, ready to spread onto a style. */
+export interface Gutters {
+  paddingTop: number;
+  paddingRight: number;
+  paddingBottom: number;
+  paddingLeft: number;
+}
+
+/** The active viewport tier: the widest matched breakpoint, or `'base'` below `sm`. */
+type GutterTier = 'base' | 'sm' | 'md' | 'lg' | 'xl';
+
+/**
+ * Per-size gutter padding (px) at each viewport tier. Padding steps up around
+ * tablet width (`md`), mirroring the design-system scale: phones get a tighter
+ * gutter, wider screens a roomier one. Values come from the shared `space`
+ * tokens so gutters stay on the spacing grid.
+ */
+const GUTTER_SCALE: Record<Exclude<Gutter, 0>, Record<GutterTier, number>> = {
+  compact: { base: space.sm, sm: space.sm, md: space.md, lg: space.md, xl: space.md },
+  base: { base: space.lg, sm: space.lg, md: space.xl, lg: space.xl, xl: space.xl },
+  wide: { base: space.xl, sm: space.xl, md: space._3xl, lg: space._3xl, xl: space._3xl },
+};
+
+/** Widest-first breakpoint table so the first match wins. */
+const TIERS: ReadonlyArray<readonly [Exclude<GutterTier, 'base'>, number]> = [
+  ['xl', BREAKPOINTS.xl],
+  ['lg', BREAKPOINTS.lg],
+  ['md', BREAKPOINTS.md],
+  ['sm', BREAKPOINTS.sm],
+];
+
+function resolveTier(width: number): GutterTier {
+  for (const [tier, minWidth] of TIERS) {
+    if (width >= minWidth) return tier;
+  }
+  return 'base';
+}
+
+function resolveEdge(size: Gutter, tier: GutterTier): number {
+  return size === 0 ? 0 : GUTTER_SCALE[size][tier];
+}
+
+/**
+ * Expand a 1/2/4-arg CSS-shorthand gutter list into `[top, right, bottom, left]`.
+ * `??` (not `||`) so an explicit `0` is preserved rather than falling through.
+ */
+function normalizeShorthand(gutters: Gutter[]): [Gutter, Gutter, Gutter, Gutter] {
+  const top = gutters[0] ?? 0;
+  const right = gutters[1] ?? top;
+  const bottom = gutters[2] ?? top;
+  const left = gutters[3] ?? right;
+  return [top, right, bottom, left];
+}
+
+/**
+ * Breakpoint-aware gutter padding. Give it CSS-shorthand gutter sizes and it
+ * returns resolved `padding*` values for the current viewport width, recomputed
+ * as the window crosses a breakpoint.
+ *
+ * @example
+ * ```tsx
+ * const gutters = useGutters(['base']);            // uniform
+ * const gutters = useGutters([0, 'wide']);         // no vertical, wide horizontal
+ * const gutters = useGutters(['compact', 'base', 0, 'base']); // t / r / b / l
+ * <View style={gutters} />
+ * ```
+ */
+export function useGutters(gutters: [Gutter]): Gutters;
+export function useGutters(gutters: [Gutter, Gutter]): Gutters;
+export function useGutters(gutters: [Gutter, Gutter, Gutter, Gutter]): Gutters;
+export function useGutters(gutters: Gutter[]): Gutters {
+  const { width } = useWindowDimensions();
+  const [top, right, bottom, left] = normalizeShorthand(gutters);
+
+  return useMemo<Gutters>(() => {
+    const tier = resolveTier(width);
+    return {
+      paddingTop: resolveEdge(top, tier),
+      paddingRight: resolveEdge(right, tier),
+      paddingBottom: resolveEdge(bottom, tier),
+      paddingLeft: resolveEdge(left, tier),
+    };
+  }, [width, top, right, bottom, left]);
+}

package/src/hooks/useHaptics.tsx

@@ -0,0 +1,69 @@
+import React, { createContext, useCallback, useContext, useMemo } from 'react';
+import { Platform } from 'react-native';
+
+import { lazyRequire } from '../utils/lazy-require';
+
+/**
+ * Lazily loads `expo-haptics`, returning `null` when it is not installed. The
+ * dependency is an optional peer, so calls degrade to a no-op when absent.
+ */
+const getHapticsModule = lazyRequire<typeof import('expo-haptics')>('expo-haptics');
+
+/** Impact strength requested by a caller. */
+export type HapticStrength = 'light' | 'medium' | 'heavy';
+
+interface BloomHapticsContextValue {
+  enabled: boolean;
+}
+
+const BloomHapticsContext = createContext<BloomHapticsContextValue>({ enabled: true });
+
+export interface BloomHapticsProviderProps {
+  /** Globally enable or disable haptics for the subtree. Defaults to `true`. */
+  enabled?: boolean;
+  children?: React.ReactNode;
+}
+
+/**
+ * Optional provider that toggles haptic feedback for its subtree — e.g. to honour
+ * a user "reduce haptics" preference. `useHaptics` defaults to enabled when no
+ * provider is present.
+ */
+export function BloomHapticsProvider({ enabled = true, children }: BloomHapticsProviderProps) {
+  const value = useMemo(() => ({ enabled }), [enabled]);
+  return <BloomHapticsContext.Provider value={value}>{children}</BloomHapticsContext.Provider>;
+}
+
+BloomHapticsProvider.displayName = 'BloomHapticsProvider';
+
+/**
+ * Returns a function that fires a haptic impact. The returned callback no-ops on
+ * web, when haptics are disabled via {@link BloomHapticsProvider}, or when the
+ * optional `expo-haptics` peer is not installed.
+ *
+ * `strength` defaults to `'light'`. Android is clamped to the light impact style
+ * regardless of `strength` — its medium/heavy motors read as too strong for UI
+ * feedback (tuned to match iOS perceived intensity).
+ */
+export function useHaptics(): (strength?: HapticStrength) => void {
+  const { enabled } = useContext(BloomHapticsContext);
+
+  return useCallback(
+    (strength: HapticStrength = 'light') => {
+      if (!enabled || Platform.OS === 'web') return;
+
+      const haptics = getHapticsModule();
+      if (!haptics) return;
+
+      const { ImpactFeedbackStyle } = haptics;
+      let style = ImpactFeedbackStyle.Light;
+      if (Platform.OS !== 'android') {
+        if (strength === 'medium') style = ImpactFeedbackStyle.Medium;
+        else if (strength === 'heavy') style = ImpactFeedbackStyle.Heavy;
+      }
+
+      void haptics.impactAsync(style);
+    },
+    [enabled],
+  );
+}

package/src/hooks/useInteractionState.ts

@@ -1,5 +1,11 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useMemo, useState } from 'react';
 
+/**
+ * Tracks a single boolean interaction flag (hovered / focused / pressed).
+ *
+ * Returns a memoized `{ state, onIn, onOut }` with stable handler identities,
+ * suitable for spreading onto Pressable-like components.
+ */
 export function useInteractionState() {
   const [state, setState] = useState(false);
 
@@ -10,7 +16,7 @@ export function useInteractionState() {
     setState(false);
   }, []);
 
-  return { state, onIn, onOut };
+  return useMemo(() => ({ state, onIn, onOut }), [state, onIn, onOut]);
 }
 
 /**

package/src/index.ts

@@ -40,6 +40,10 @@ export type {
 export { useInteractionState } from './hooks/useInteractionState';
 export { useDelayedLoading } from './hooks/useDelayedLoading';
 export { useThrottledValue } from './hooks/useThrottledValue';
+export { useHaptics, BloomHapticsProvider } from './hooks/useHaptics';
+export type { HapticStrength, BloomHapticsProviderProps } from './hooks/useHaptics';
+export { useGutters } from './hooks/useGutters';
+export type { Gutter, Gutters } from './hooks/useGutters';
 
 // Icons
 export * as Icons from './icons';
@@ -97,12 +101,28 @@ export * as Typography from './typography';
 export * as Skeleton from './skeleton';
 export * as Grid from './grid';
 export { Fill } from './fill';
+export { MediaInsetBorder } from './media-inset-border';
+export type { MediaInsetBorderProps } from './media-inset-border';
 export { IconCircle } from './icon-circle';
 export { ConnectionDots } from './connection-dots';
 export type { ConnectionDotsProps } from './connection-dots';
 export { BenefitRow, BenefitList } from './benefit-list';
 export type { BenefitRowProps, BenefitListProps } from './benefit-list';
 
+// Interaction primitives
+export { PressableScale } from './pressable-scale';
+export type { PressableScaleProps } from './pressable-scale';
+export { PressableWithHover } from './pressable-with-hover';
+export type { PressableWithHoverProps } from './pressable-with-hover';
+export { SubtleHover } from './subtle-hover';
+export type { SubtleHoverProps } from './subtle-hover';
+
+// Motion presets (Reanimated enter/exit + directional screen transition)
+export { ScaleAndFadeIn, ScaleAndFadeOut, ShrinkAndPop, ScreenTransition } from './motion';
+export type { ScreenTransitionProps, ScreenTransitionDirection } from './motion';
+export { AnimatedCheck } from './animated-check';
+export type { AnimatedCheckProps, AnimatedCheckRef } from './animated-check';
+
 // Form components
 export * from './text-field';
 export * from './segmented-control';

package/src/index.web.ts

@@ -45,6 +45,10 @@ export type {
 export { useInteractionState } from './hooks/useInteractionState';
 export { useDelayedLoading } from './hooks/useDelayedLoading';
 export { useThrottledValue } from './hooks/useThrottledValue';
+export { useHaptics, BloomHapticsProvider } from './hooks/useHaptics';
+export type { HapticStrength, BloomHapticsProviderProps } from './hooks/useHaptics';
+export { useGutters } from './hooks/useGutters';
+export type { Gutter, Gutters } from './hooks/useGutters';
 
 // Icons
 export * as Icons from './icons';
@@ -102,12 +106,28 @@ export * as Typography from './typography';
 export * as Skeleton from './skeleton';
 export * as Grid from './grid';
 export { Fill } from './fill';
+export { MediaInsetBorder } from './media-inset-border';
+export type { MediaInsetBorderProps } from './media-inset-border';
 export { IconCircle } from './icon-circle';
 export { ConnectionDots } from './connection-dots/index.web';
 export type { ConnectionDotsProps } from './connection-dots/index.web';
 export { BenefitRow, BenefitList } from './benefit-list';
 export type { BenefitRowProps, BenefitListProps } from './benefit-list';
 
+// Interaction primitives
+export { PressableScale } from './pressable-scale';
+export type { PressableScaleProps } from './pressable-scale';
+export { PressableWithHover } from './pressable-with-hover';
+export type { PressableWithHoverProps } from './pressable-with-hover';
+export { SubtleHover } from './subtle-hover';
+export type { SubtleHoverProps } from './subtle-hover';
+
+// Motion presets (Reanimated enter/exit + directional screen transition)
+export { ScaleAndFadeIn, ScaleAndFadeOut, ShrinkAndPop, ScreenTransition } from './motion';
+export type { ScreenTransitionProps, ScreenTransitionDirection } from './motion';
+export { AnimatedCheck } from './animated-check';
+export type { AnimatedCheckProps, AnimatedCheckRef } from './animated-check';
+
 // Form components
 export * from './text-field';
 export * from './segmented-control';

package/src/media-inset-border/MediaInsetBorder.stories.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import { Image, View } from 'react-native';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { MediaInsetBorder } from './index';
+
+const meta: Meta<typeof MediaInsetBorder> = {
+  title: 'Components/MediaInsetBorder',
+  component: MediaInsetBorder,
+  argTypes: {
+    opaque: { control: 'boolean' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof MediaInsetBorder>;
+
+const SAMPLE_URI =
+  'https://images.unsplash.com/photo-1526779259212-939e64788e3c?w=400&q=80';
+
+export const OverImage: Story = {
+  render: (args) => (
+    <View style={{ width: 240, height: 160, borderRadius: 8, overflow: 'hidden' }}>
+      <Image source={{ uri: SAMPLE_URI }} style={{ width: '100%', height: '100%' }} />
+      <MediaInsetBorder {...args} />
+    </View>
+  ),
+};
+
+export const OverFlatSurface: Story = {
+  render: (args) => (
+    <View
+      style={{
+        width: 240,
+        height: 160,
+        borderRadius: 8,
+        backgroundColor: '#e5e7eb',
+      }}
+    >
+      <MediaInsetBorder {...args} />
+    </View>
+  ),
+};
+
+export const Opaque: Story = {
+  args: { opaque: true },
+  render: (args) => (
+    <View
+      style={{
+        width: 240,
+        height: 160,
+        borderRadius: 8,
+        backgroundColor: '#e5e7eb',
+      }}
+    >
+      <MediaInsetBorder {...args} />
+    </View>
+  ),
+};

package/src/media-inset-border/MediaInsetBorder.tsx

@@ -0,0 +1,72 @@
+import React from 'react';
+import {
+  PixelRatio,
+  Platform,
+  StyleSheet,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { Fill } from '../fill';
+import { borderRadius } from '../styles/tokens';
+import { useTheme } from '../theme';
+
+/**
+ * A 1px (hairline) inset border reads too heavy on high-DPI web displays, so we
+ * drop to 0.5px there. On native the platform hairline is already correct, and
+ * `PixelRatio` is only consulted on web.
+ */
+const HAIRLINE_WIDTH =
+  Platform.OS === 'web' && PixelRatio.get() > 1 ? 0.5 : StyleSheet.hairlineWidth;
+
+export interface MediaInsetBorderProps {
+  /**
+   * Render a solid, full-contrast border instead of the default softened one.
+   * Use where the inset border must line up with adjacent opaque borders, such
+   * as external link-preview cards.
+   */
+  opaque?: boolean;
+  /**
+   * Extra style merged last. Override `borderRadius` here to match the corner
+   * radius of the surrounding media box.
+   */
+  style?: StyleProp<ViewStyle>;
+  children?: React.ReactNode;
+}
+
+/**
+ * A theme-aware hairline border painted just inside a media box (image, avatar,
+ * embed) to separate it from the surrounding background. Absolutely positioned
+ * to fill its parent (built on {@link Fill}) and non-interactive.
+ */
+export function MediaInsetBorder({ opaque, style, children }: MediaInsetBorderProps) {
+  const theme = useTheme();
+
+  return (
+    <Fill
+      style={[
+        styles.base,
+        { borderColor: theme.colors.border },
+        !opaque && styles.soft,
+        style,
+      ]}
+    >
+      {children}
+    </Fill>
+  );
+}
+
+MediaInsetBorder.displayName = 'MediaInsetBorder';
+
+const styles = StyleSheet.create({
+  base: {
+    borderRadius: borderRadius.sm,
+    borderWidth: HAIRLINE_WIDTH,
+    pointerEvents: 'none',
+  },
+  // Non-opaque: same border color at reduced opacity so it reads as a subtle,
+  // lower-contrast separator rather than a hard edge.
+  soft: {
+    opacity: 0.6,
+  },
+});

package/src/media-inset-border/index.ts

@@ -0,0 +1,2 @@
+export { MediaInsetBorder } from './MediaInsetBorder';
+export type { MediaInsetBorderProps } from './MediaInsetBorder';

package/src/motion/Motion.stories.tsx

@@ -0,0 +1,99 @@
+import React, { useState } from 'react';
+import { Pressable, Text, View } from 'react-native';
+import Animated from 'react-native-reanimated';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ScaleAndFadeIn, ScaleAndFadeOut, ScreenTransition, ShrinkAndPop } from './index';
+
+const meta: Meta = {
+  title: 'Motion/Presets',
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+function Toggle({ children }: { children: React.ReactNode }) {
+  const [shown, setShown] = useState(true);
+  return (
+    <View style={{ gap: 16, alignItems: 'flex-start' }}>
+      <Pressable
+        accessibilityLabel="Toggle"
+        onPress={() => setShown((v) => !v)}
+        style={{
+          paddingVertical: 8,
+          paddingHorizontal: 16,
+          borderRadius: 8,
+          backgroundColor: '#111827',
+        }}
+      >
+        <Text style={{ color: 'white', fontWeight: '600' }}>{shown ? 'Hide' : 'Show'}</Text>
+      </Pressable>
+      <View style={{ height: 96, justifyContent: 'center' }}>{shown ? children : null}</View>
+    </View>
+  );
+}
+
+const card = {
+  width: 160,
+  height: 72,
+  borderRadius: 16,
+  backgroundColor: '#6366f1',
+  alignItems: 'center',
+  justifyContent: 'center',
+} as const;
+
+export const ScaleAndFade: Story = {
+  render: () => (
+    <Toggle>
+      <Animated.View entering={ScaleAndFadeIn} exiting={ScaleAndFadeOut} style={card}>
+        <Text style={{ color: 'white', fontWeight: '700' }}>Scale + Fade</Text>
+      </Animated.View>
+    </Toggle>
+  ),
+};
+
+export const Pop: Story = {
+  render: () => (
+    <Toggle>
+      <Animated.View entering={ScaleAndFadeIn} exiting={ShrinkAndPop} style={card}>
+        <Text style={{ color: 'white', fontWeight: '700' }}>Shrink + Pop</Text>
+      </Animated.View>
+    </Toggle>
+  ),
+};
+
+export const Transition: Story = {
+  render: () => {
+    function Demo() {
+      const [forward, setForward] = useState(true);
+      return (
+        <View style={{ gap: 16, alignItems: 'flex-start' }}>
+          <Pressable
+            accessibilityLabel="Swap direction"
+            onPress={() => setForward((v) => !v)}
+            style={{
+              paddingVertical: 8,
+              paddingHorizontal: 16,
+              borderRadius: 8,
+              backgroundColor: '#111827',
+            }}
+          >
+            <Text style={{ color: 'white', fontWeight: '600' }}>
+              Direction: {forward ? 'forward' : 'backward'}
+            </Text>
+          </Pressable>
+          <ScreenTransition
+            key={forward ? 'forward' : 'backward'}
+            direction={forward ? 'forward' : 'backward'}
+            enabledWeb
+            style={card}
+          >
+            <Text style={{ color: 'white', fontWeight: '700' }}>Screen</Text>
+          </ScreenTransition>
+        </View>
+      );
+    }
+    return <Demo />;
+  },
+};

package/src/motion/ScreenTransition.tsx

@@ -0,0 +1,71 @@
+import React from 'react';
+import { Platform, type StyleProp, type ViewStyle } from 'react-native';
+import Animated, {
+  Easing,
+  FadeIn,
+  FadeOut,
+  SlideInLeft,
+  SlideInRight,
+} from 'react-native-reanimated';
+
+/** Direction the incoming screen travels. */
+export type ScreenTransitionDirection = 'forward' | 'backward';
+
+export interface ScreenTransitionProps {
+  /**
+   * `'forward'` slides the new screen in from the right, `'backward'` from the
+   * left — matching a push / pop navigation gesture.
+   */
+  direction: ScreenTransitionDirection;
+  /**
+   * Enable the transition on web. Off by default: Reanimated layout animations
+   * are fragile across web bundlers, so web opts in explicitly and gets a
+   * lightweight cross-fade rather than a slide.
+   */
+  enabledWeb?: boolean;
+  style?: StyleProp<ViewStyle>;
+  children?: React.ReactNode;
+}
+
+/** CSS-smooth deceleration for the native slide. */
+const SLIDE_EASING = Easing.out(Easing.exp);
+/** Web cross-fade duration (ms) — "totally vibes based", per the Bluesky original. */
+const WEB_FADE_DURATION = 90;
+
+/**
+ * Wraps `children` in a Reanimated layout-animated view that slides in
+ * directionally on native and (optionally) cross-fades on web. Ported from
+ * Bluesky's `ScreenTransition`.
+ *
+ * On web the slide is intentionally dropped: layout animations there are
+ * unreliable, so `enabledWeb` gates a simple fade and the default is no
+ * transition at all.
+ */
+export function ScreenTransition({
+  direction,
+  enabledWeb,
+  style,
+  children,
+}: ScreenTransitionProps) {
+  const isWeb = Platform.OS === 'web';
+
+  const entering = isWeb
+    ? enabledWeb
+      ? FadeIn.duration(WEB_FADE_DURATION)
+      : undefined
+    : (direction === 'forward' ? SlideInRight : SlideInLeft).easing(SLIDE_EASING);
+
+  const exiting = isWeb
+    ? enabledWeb
+      ? FadeOut.duration(WEB_FADE_DURATION)
+      : undefined
+    : FadeOut.duration(WEB_FADE_DURATION);
+
+  return (
+    <Animated.View entering={entering} exiting={exiting} style={style}>
+      {children}
+    </Animated.View>
+  );
+}
+
+ScreenTransition.displayName = 'ScreenTransition';

package/src/motion/index.ts

@@ -0,0 +1,3 @@
+export { ScaleAndFadeIn, ScaleAndFadeOut, ShrinkAndPop } from './motion';
+export { ScreenTransition } from './ScreenTransition';
+export type { ScreenTransitionProps, ScreenTransitionDirection } from './ScreenTransition';

package/src/motion/motion.ts

@@ -0,0 +1,75 @@
+import {
+  withDelay,
+  withSequence,
+  withTiming,
+  type LayoutAnimation,
+} from 'react-native-reanimated';
+
+/**
+ * Reanimated custom layout-animation presets. Each is a worklet builder
+ * compatible with an `Animated.View`'s `entering` / `exiting` prop:
+ *
+ * ```tsx
+ * <Animated.View entering={ScaleAndFadeIn} exiting={ScaleAndFadeOut} />
+ * ```
+ *
+ * Ported from Bluesky's custom-animation set. The `'worklet'` directive is
+ * preserved through Bloom's build; the consuming app's Metro + reanimated Babel
+ * plugin transforms it so the animation runs on the UI thread (same path the
+ * existing `bottom-sheet` gesture worklets rely on).
+ */
+
+/** Entering: fade in while growing from 70% to full size. */
+export const ScaleAndFadeIn: () => LayoutAnimation = () => {
+  'worklet';
+  return {
+    animations: {
+      opacity: withTiming(1),
+      transform: [{ scale: withTiming(1) }],
+    },
+    initialValues: {
+      opacity: 0,
+      transform: [{ scale: 0.7 }],
+    },
+  };
+};
+
+/** Exiting counterpart to {@link ScaleAndFadeIn}: fade out while shrinking to 70%. */
+export const ScaleAndFadeOut: () => LayoutAnimation = () => {
+  'worklet';
+  return {
+    animations: {
+      opacity: withTiming(0),
+      transform: [{ scale: withTiming(0.7) }],
+    },
+    initialValues: {
+      opacity: 1,
+      transform: [{ scale: 1 }],
+    },
+  };
+};
+
+/**
+ * Exiting with a brief "pop": the scale dips to 70%, overshoots to 110%, and the
+ * element fades out. Good for confirming a tapped or removed item.
+ */
+export const ShrinkAndPop: () => LayoutAnimation = () => {
+  'worklet';
+  return {
+    animations: {
+      opacity: withDelay(125, withTiming(0, { duration: 125 })),
+      transform: [
+        {
+          scale: withSequence(
+            withTiming(0.7, { duration: 75 }),
+            withTiming(1.1, { duration: 150 }),
+          ),
+        },
+      ],
+    },
+    initialValues: {
+      opacity: 1,
+      transform: [{ scale: 1 }],
+    },
+  };
+};