@oxyhq/bloom 0.32.1 → 0.33.1

package/lib/typescript/module/zoomable-image-gallery/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/constants.ts"],"names":[],"mappings":"AAEA,0EAA0E;AAC1E,eAAO,MAAM,YAAY,MAAM,CAAC;AAChC,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,uDAAuD;AACvD,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,0FAA0F;AAC1F,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,WAAW;;;;CAAsD,CAAC;AAC/E,eAAO,MAAM,YAAY;;;;CAAuD,CAAC;AACjF,eAAO,MAAM,gBAAgB;;;;CAAsD,CAAC;AAEpF,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,IAAsB,CAAC"}

package/lib/typescript/module/zoomable-image-gallery/index.d.ts

@@ -0,0 +1,3 @@
+export { ZoomableImageGallery, ZoomableImageGallery as default } from './ZoomableImageGallery';
+export type { ZoomableImageGalleryHandle, ZoomableImageGalleryProps, GalleryImage, MeasureThumb, MeasuredRect, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/zoomable-image-gallery/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,IAAI,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAC/F,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,SAAS,CAAC"}

package/lib/typescript/module/zoomable-image-gallery/types.d.ts

@@ -0,0 +1,46 @@
+export interface GalleryImage {
+    /** Source URI rendered both as the thumbnail and the zoomed image. */
+    uri: string;
+    /**
+     * Author-authored accessibility description (Bluesky-style "ALT"). When present,
+     * shown as a caption at the bottom of the fullscreen viewer for the active image.
+     */
+    alt?: string;
+    /**
+     * Optional intrinsic aspect ratio (width / height) supplied by the consumer.
+     * When known ahead of time it avoids a first-frame `Image.getSize` round-trip.
+     */
+    aspectRatio?: number;
+}
+/**
+ * On-screen rectangle of a thumbnail, used to fly the zoom transition to/from
+ * the tapped image. Bloom-owned so consumers don't depend on an app-local shape.
+ */
+export interface MeasuredRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Resolve the on-screen rect of the thumbnail at `index` within the SAME
+ * images-only subset the gallery opens/pages in, so the close animation can fly
+ * back to the image currently being viewed. Resolves `null` when the thumbnail
+ * ref is missing (unmounted/virtualized), in which case the gallery falls back
+ * to a plain center fade-out.
+ */
+export type MeasureThumb = (index: number) => Promise<MeasuredRect | null>;
+export interface ZoomableImageGalleryHandle {
+    /**
+     * Open the gallery at `index` within `images`, animating the zoom from the
+     * tapped thumbnail's measured screen rect (when provided).
+     */
+    open: (images: GalleryImage[], index: number, rect?: MeasuredRect) => void;
+}
+export interface ZoomableImageGalleryProps {
+    /** Measures any thumbnail by its images-only subset index, used on dismiss. */
+    measureThumb?: MeasureThumb;
+    /** Corner radius applied to the zoomed images. Defaults to `DEFAULT_CORNER_RADIUS`. */
+    cornerRadius?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/module/zoomable-image-gallery/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/zoomable-image-gallery/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;AAE3E,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,IAAI,CAAC;CAC5E;AAED,MAAM,WAAW,yBAAyB;IACxC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.32.1",
+  "version": "0.33.1",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -39,6 +39,17 @@
         "default": "./lib/commonjs/image-resolver/index.js"
       }
     },
+    "./image-aspect-ratio-cache": {
+      "react-native": "./src/image-aspect-ratio-cache/index.ts",
+      "import": {
+        "types": "./lib/typescript/module/image-aspect-ratio-cache/index.d.ts",
+        "default": "./lib/module/image-aspect-ratio-cache/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/image-aspect-ratio-cache/index.d.ts",
+        "default": "./lib/commonjs/image-aspect-ratio-cache/index.js"
+      }
+    },
     "./theme": {
       "react-native": "./src/theme/index.ts",
       "import": {
@@ -382,6 +393,17 @@
         "default": "./lib/commonjs/media-inset-border/index.js"
       }
     },
+    "./zoomable-image-gallery": {
+      "react-native": "./src/zoomable-image-gallery/index.ts",
+      "import": {
+        "types": "./lib/typescript/module/zoomable-image-gallery/index.d.ts",
+        "default": "./lib/module/zoomable-image-gallery/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/zoomable-image-gallery/index.d.ts",
+        "default": "./lib/commonjs/zoomable-image-gallery/index.js"
+      }
+    },
     "./pressable-scale": {
       "react-native": "./src/pressable-scale/index.ts",
       "import": {
@@ -1054,8 +1076,10 @@
     "@types/react-dom": "^19.2.3",
     "@types/react-native": "*",
     "@vitejs/plugin-react": "^6.0.2",
+    "expo-blur": "~56.0.3",
     "expo-font": "^56.0.5",
     "expo-haptics": "~56.0.3",
+    "expo-image": "~56.0.11",
     "expo-router": "^56.0.0",
     "jest": "^30.3.0",
     "jest-environment-jsdom": "^30.4.1",
@@ -1079,8 +1103,10 @@
   },
   "peerDependencies": {
     "expo": "*",
+    "expo-blur": "*",
     "expo-font": "*",
     "expo-haptics": "*",
+    "expo-image": "*",
     "expo-router": ">=3.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",

package/src/__tests__/Command.test.tsx

@@ -1,8 +1,10 @@
-import React from 'react';
+import React, { useImperativeHandle } from 'react';
 import { act, fireEvent, render } from '@testing-library/react-native';
 
 import { Command } from '../command';
+import { createCommand } from '../command/Command';
 import type { CommandItem } from '../command';
+import type { DialogProps } from '../dialog';
 import { BloomThemeProvider } from '../theme/BloomThemeProvider';
 
 function renderWithTheme(ui: React.ReactElement) {
@@ -104,4 +106,123 @@ describe('Command (built on Dialog)', () => {
     expect(onSelect).toHaveBeenCalledTimes(1);
     expect(onClose).toHaveBeenCalledTimes(1);
   });
+
+  // The migration off the controlled `open` prop onto the imperative `control`
+  // handle (making `Command` the last controlled-mode `Dialog` consumer to move
+  // over). These pin the fix at the prop boundary between `Command` and the
+  // underlying `Dialog`, using a prop-capturing mock `Dialog` so the assertions
+  // are deterministic and platform-agnostic — mirroring `AlertDialog`'s round.
+  describe('control-mode bridge', () => {
+    function captureDialogProps() {
+      const captured: { props?: DialogProps } = {};
+      const MockDialog = (props: DialogProps) => {
+        captured.props = props;
+        return null;
+      };
+      return { captured, MockDialog };
+    }
+
+    it('drives the underlying Dialog imperatively (control), never the controlled `open` prop', () => {
+      const { captured, MockDialog } = captureDialogProps();
+      const TestCommand = createCommand(MockDialog);
+      renderWithTheme(
+        <TestCommand visible onClose={() => {}} items={makeItems(() => {})} />,
+      );
+      // The whole point of the migration: `Command` must take the Dialog's
+      // imperative/uncontrolled branch (the one that plays the exit animation on
+      // dismiss), so an imperative `control` handle is passed and the controlled
+      // `open` boolean — which fires `onClose` synchronously — is never set.
+      expect(captured.props?.control).toBeDefined();
+      expect(captured.props?.open).toBeUndefined();
+    });
+
+    // A mock Dialog that registers the real imperative contract on `control.ref`
+    // (so `Command`'s `control.open()` / `control.close()` proxy through it) and
+    // fires `onClose` when imperatively closed — modelling the real Dialog,
+    // which invokes `onClose` only AFTER its exit animation settles.
+    function ImperativeMockDialog(props: DialogProps) {
+      const onCloseRef = React.useRef(props.onClose);
+      onCloseRef.current = props.onClose;
+      useImperativeHandle(
+        props.control?.ref,
+        () => ({
+          open: () => {},
+          // The real Dialog fires `onClose` post-exit-animation.
+          close: () => onCloseRef.current?.(),
+        }),
+        [],
+      );
+      return null;
+    }
+
+    it('opens the Dialog imperatively on mount when visible, and closes it when visible flips false', () => {
+      const spies = { open: jest.fn(), close: jest.fn() };
+      const MockDialog = (props: DialogProps) => {
+        useImperativeHandle(props.control?.ref, () => spies, []);
+        return null;
+      };
+      const TestCommand = createCommand(MockDialog);
+      const { rerender } = renderWithTheme(
+        <TestCommand visible onClose={() => {}} items={makeItems(() => {})} />,
+      );
+      expect(spies.open).toHaveBeenCalledTimes(1);
+      expect(spies.close).not.toHaveBeenCalled();
+
+      act(() => {
+        rerender(
+          <BloomThemeProvider mode="light" colorPreset="teal">
+            <TestCommand
+              visible={false}
+              onClose={() => {}}
+              items={makeItems(() => {})}
+            />
+          </BloomThemeProvider>,
+        );
+      });
+      expect(spies.close).toHaveBeenCalledTimes(1);
+    });
+
+    it('forwards a user dismissal (backdrop / Escape) through onClose', () => {
+      const spyRef: { fn?: () => void } = {};
+      const MockDialog = (props: DialogProps) => {
+        spyRef.fn = props.onClose;
+        return null;
+      };
+      const onClose = jest.fn();
+      const TestCommand = createCommand(MockDialog);
+      renderWithTheme(
+        <TestCommand visible onClose={onClose} items={makeItems(() => {})} />,
+      );
+      // The real Dialog fires `onClose` once its exit animation settles after a
+      // backdrop / Escape dismissal. `Command` must forward that to the consumer.
+      act(() => {
+        spyRef.fn?.();
+      });
+      expect(onClose).toHaveBeenCalledTimes(1);
+    });
+
+    it('does not re-enter onClose when the consumer closes it (visible → false)', () => {
+      const onClose = jest.fn();
+      const TestCommand = createCommand(ImperativeMockDialog);
+      const { rerender } = renderWithTheme(
+        <TestCommand visible onClose={onClose} items={makeItems(() => {})} />,
+      );
+      act(() => {
+        rerender(
+          <BloomThemeProvider mode="light" colorPreset="teal">
+            <TestCommand
+              visible={false}
+              onClose={onClose}
+              items={makeItems(() => {})}
+            />
+          </BloomThemeProvider>,
+        );
+      });
+      // A consumer-initiated close flips `visible` to false → `Command`
+      // imperatively `close()`s the Dialog (which fires its post-exit `onClose`).
+      // That programmatic close must NOT re-enter the consumer's `onClose`,
+      // preserving the previous controlled semantics.
+      expect(onClose).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/command/Command.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import {
   Platform,
   ScrollView,
@@ -15,6 +15,7 @@ import { Kbd } from '../kbd';
 import { SearchInput } from '../search-input';
 import { fontSize, space } from '../styles/tokens';
 import type { DialogProps } from '../dialog';
+import { useDialogControl } from '../dialog/context';
 import type { CommandItem, CommandProps } from './types';
 
 type DialogComponent = React.ComponentType<DialogProps>;
@@ -48,6 +49,20 @@ interface FlatEntry {
  * `SearchInput`, an `Item` results list and `Kbd` shortcut hints. Items group
  * by their `group` field (ungrouped first). On web the list is
  * keyboard-navigable (Up/Down/Enter); on native, tap to select.
+ *
+ * Control mode — IMPERATIVE, not controlled. `Command` keeps its public
+ * *controlled* API (`visible` boolean + `onClose`) but internally bridges it
+ * onto the Dialog's imperative `useDialogControl()` handle, exactly like
+ * `AlertDialog`. This makes `Command` the LAST controlled-`open` `Dialog`
+ * consumer to move onto the imperative path every other surface uses
+ * (`alert()`, `confirm()`, native `Menu`/`Select`/`ContextMenu`, Mention's
+ * dialogs), so there is one code path across the ecosystem. It also guarantees
+ * the palette's exit animation on the dismiss path even for a consumer that
+ * unmounts the palette in response to `onClose` (`{open && <Command …/>}`): the
+ * imperative `close()` runs the exit animation FIRST and fires `onClose` only
+ * once it settles, whereas the controlled `open` path fires `onClose`
+ * synchronously — which, for an unmount-on-close consumer, would tear the
+ * surface down before it could animate out.
  */
 export function createCommand(Dialog: DialogComponent) {
   const Command = function Command({
@@ -64,6 +79,7 @@ export function createCommand(Dialog: DialogComponent) {
     testID,
   }: CommandProps) {
     const theme = useTheme();
+    const control = useDialogControl();
     const searchRef = useRef<TextInput>(null);
     const [activeIndex, setActiveIndex] = useState(0);
 
@@ -142,6 +158,37 @@ export function createCommand(Dialog: DialogComponent) {
     [setQuery, onClose],
   );
 
+  // Bridge the public *controlled* `visible` prop onto the Dialog's imperative
+  // open/close (mirrors `AlertDialog`). `control` is referentially stable
+  // (memoised on its id), so this effect only re-runs when `visible` actually
+  // flips. Opening straight from an effect on mount matches bloom's own
+  // `AutoMountedDialog`. When a consumer flips `visible` to `false` (their own
+  // close, or after a select), we imperatively `close()` so the exit animation
+  // still plays.
+  const closingFromPropRef = useRef(false);
+  useEffect(() => {
+    if (visible) {
+      control.open();
+      return;
+    }
+    closingFromPropRef.current = true;
+    control.close();
+  }, [visible, control]);
+
+  // The Dialog fires `onClose` after the exit animation settles (imperative
+  // mode). Forward ONLY user-initiated dismissals (backdrop / Escape) to the
+  // consumer — a consumer-initiated close (they flipped `visible` to `false`,
+  // e.g. `select` already called `onClose`) must not re-enter `onClose`,
+  // preserving the previous controlled semantics where a programmatic close
+  // does not fire `onClose` a second time.
+  const handleClose = useCallback(() => {
+    if (closingFromPropRef.current) {
+      closingFromPropRef.current = false;
+      return;
+    }
+    onClose();
+  }, [onClose]);
+
   // Web keyboard navigation on the search input.
   const webKeyHandler: Record<string, unknown> =
     Platform.OS === 'web'
@@ -172,8 +219,8 @@ export function createCommand(Dialog: DialogComponent) {
 
   return (
     <Dialog
-      open={visible}
-      onClose={onClose}
+      control={control}
+      onClose={handleClose}
       placement="center"
       dismissOnBackdrop
       maxWidth={COMMAND_MAX_WIDTH}

package/src/hooks/index.ts

@@ -7,3 +7,4 @@ export { useHaptics, BloomHapticsProvider } from './useHaptics';
 export type { HapticStrength, BloomHapticsProviderProps } from './useHaptics';
 export { useGutters } from './useGutters';
 export type { Gutter, Gutters } from './useGutters';
+export { useImagePreload, preloadImage } from './useImagePreload';

package/src/hooks/useImagePreload.ts

@@ -0,0 +1,51 @@
+import { useEffect, useRef, useMemo } from 'react';
+import { Image } from 'react-native';
+
+/**
+ * Hook to preload images for better perceived performance
+ * Preloads images when they're likely to be viewed soon
+ */
+export function useImagePreload(urls: (string | undefined)[], enabled: boolean = true) {
+  const preloadedRef = useRef<Set<string>>(new Set());
+
+  // Memoize valid URLs to avoid unnecessary re-runs
+  const validUrls = useMemo(() => {
+    return urls.filter((url): url is string =>
+      Boolean(url && (url.startsWith('http://') || url.startsWith('https://')))
+    );
+  }, [urls]);
+
+  useEffect(() => {
+    if (!enabled || !validUrls.length) return;
+
+    validUrls.forEach((url) => {
+      if (preloadedRef.current.has(url)) return;
+
+      preloadedRef.current.add(url);
+      Image.prefetch(url).catch(() => {
+        // Silently handle prefetch errors - remove from set on error to allow retry
+        preloadedRef.current.delete(url);
+      });
+    });
+  }, [validUrls, enabled]);
+
+  // Limit cache size to prevent memory issues (keep last 1000)
+  useEffect(() => {
+    if (preloadedRef.current.size > 1000) {
+      const entries = Array.from(preloadedRef.current);
+      const toRemove = entries.slice(0, entries.length - 1000);
+      toRemove.forEach(url => preloadedRef.current.delete(url));
+    }
+  }, [validUrls]);
+}
+
+/**
+ * Preload a single image
+ */
+export function preloadImage(url: string | undefined): void {
+  if (!url || !url.startsWith('http')) return;
+
+  Image.prefetch(url).catch(() => {
+    // Silently handle prefetch errors
+  });
+}

package/src/image-aspect-ratio-cache/imageAspectRatioCache.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared module-scoped cache of image aspect ratios (width / height), keyed by
+ * the image source URI.
+ *
+ * Intended for a thumbnail renderer and a fullscreen viewer (e.g.
+ * `@oxyhq/bloom/zoomable-image-gallery`) sharing the SAME image URI to read
+ * from and write to this one map, so an image already resolved as a thumbnail
+ * has its ratio on hand when it opens "big" — no second cache, no duplicate
+ * `Image.getSize` round-trip on the hot path. If the two surfaces render
+ * different URI variants of the same image (e.g. a smaller thumbnail variant
+ * vs. a larger lightbox variant), pass the known ratio through explicitly
+ * (`GalleryImage.aspectRatio`) instead of relying on cache-key reuse.
+ */
+import { Image } from 'react-native';
+
+/** Fallback ratio used when a remote image's intrinsic size cannot be read. */
+export const DEFAULT_ASPECT_RATIO = 4 / 3;
+
+const aspectRatioCache = new Map<string, number>();
+
+export const getAspectRatio = (uri: string): number | undefined => aspectRatioCache.get(uri);
+
+export const hasAspectRatio = (uri: string): boolean => aspectRatioCache.has(uri);
+
+export const setAspectRatio = (uri: string, ratio: number): void => {
+  if (uri && ratio > 0 && Number.isFinite(ratio)) {
+    aspectRatioCache.set(uri, ratio);
+  }
+};
+
+/**
+ * Resolve the aspect ratio for `uri`, returning the cached value immediately on
+ * a hit and otherwise fetching the intrinsic size via `Image.getSize`, writing
+ * the result back into the shared cache. On failure the shared
+ * `DEFAULT_ASPECT_RATIO` is cached and returned so callers never deadlock on a
+ * broken image.
+ */
+export const fetchAspectRatio = (uri: string): Promise<number> => {
+  const cached = aspectRatioCache.get(uri);
+  if (cached !== undefined) {
+    return Promise.resolve(cached);
+  }
+  return new Promise<number>((resolve) => {
+    Image.getSize(
+      uri,
+      (width, height) => {
+        if (width > 0 && height > 0) {
+          const ratio = width / height;
+          aspectRatioCache.set(uri, ratio);
+          resolve(ratio);
+          return;
+        }
+        aspectRatioCache.set(uri, DEFAULT_ASPECT_RATIO);
+        resolve(DEFAULT_ASPECT_RATIO);
+      },
+      () => {
+        aspectRatioCache.set(uri, DEFAULT_ASPECT_RATIO);
+        resolve(DEFAULT_ASPECT_RATIO);
+      }
+    );
+  });
+};

package/src/image-aspect-ratio-cache/index.ts

@@ -0,0 +1,7 @@
+export {
+  getAspectRatio,
+  hasAspectRatio,
+  setAspectRatio,
+  fetchAspectRatio,
+  DEFAULT_ASPECT_RATIO,
+} from './imageAspectRatioCache';

package/src/index.ts

@@ -44,6 +44,7 @@ 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';
+export { useImagePreload, preloadImage } from './hooks/useImagePreload';
 
 // Icons
 export * as Icons from './icons';

package/src/index.web.ts

@@ -49,6 +49,7 @@ 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';
+export { useImagePreload, preloadImage } from './hooks/useImagePreload';
 
 // Icons
 export * as Icons from './icons';