@oxyhq/bloom 0.32.0 → 0.33.0

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.0",
+  "version": "0.33.0",
   "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__/Fab.web.test.tsx

@@ -138,4 +138,66 @@ describe('Fab.web', () => {
     expect(fab.style.width).toBe('56px');
     expect(fab.style.height).toBe('56px');
   });
+
+  // Regression: `style` / `labelStyle` are React-Native `StyleProp`s (array-
+  // capable — the native fork passes `style={[placementStyle(...), {...}, style]}`).
+  // Spreading a raw array into the DOM element's inline style used to produce
+  // numeric keys and throw at runtime:
+  //   "Failed to set an indexed property [0] on 'CSSStyleDeclaration'".
+  describe('style prop flattening', () => {
+    it('renders without crashing when style is an array with a falsy hole', () => {
+      const showBorder = false;
+      const c = mount(
+        <Fab
+          accessibilityLabel="Add"
+          icon={<span>+</span>}
+          style={[{ marginBottom: 10 }, showBorder && { borderColor: 'rgb(9, 9, 9)' }]}
+        />,
+      );
+      const fab = getByRole(c, 'button');
+      expect(fab.tagName).toBe('BUTTON');
+      // The array is flattened onto the button; falsy entries are skipped.
+      expect(fab.style.marginBottom).toBe('10px');
+      // The crash signature: a leaked numeric ("0") style key.
+      expect(fab.getAttribute('style') ?? '').not.toMatch(/(^|;)\s*0\s*:/);
+    });
+
+    it('later array entries win, mirroring RN precedence, and override the base container style', () => {
+      const c = mount(
+        <Fab
+          accessibilityLabel="Add"
+          icon={<span>+</span>}
+          // `zIndex: 7` overrides the container's default zIndex (50).
+          style={[{ zIndex: 3 }, { zIndex: 7, backgroundColor: 'rgb(1, 2, 3)' }]}
+        />,
+      );
+      const fab = getByRole(c, 'button');
+      expect(fab.style.zIndex).toBe('7');
+      // Caller style is spread after the variant container style, so it wins.
+      expect(fab.style.backgroundColor).toBe('rgb(1, 2, 3)');
+    });
+
+    it('accepts a single style object', () => {
+      const c = mount(
+        <Fab accessibilityLabel="Add" icon={<span>+</span>} style={{ marginBottom: 5 }} />,
+      );
+      expect(getByRole(c, 'button').style.marginBottom).toBe('5px');
+    });
+
+    it('flattens an array labelStyle onto the extended-FAB label span', () => {
+      const c = mount(
+        <Fab
+          label="Compose"
+          icon={<span>+</span>}
+          labelStyle={[{ fontWeight: '700' }, false, { letterSpacing: 2 }]}
+        />,
+      );
+      const label = getByText(c, 'Compose');
+      expect(label.tagName).toBe('SPAN');
+      expect(label.style.fontWeight).toBe('700');
+      expect(label.style.letterSpacing).toBe('2px');
+      // No leaked numeric style key from the array spread.
+      expect(label.getAttribute('style') ?? '').not.toMatch(/(^|;)\s*0\s*:/);
+    });
+  });
 });

package/src/button/Button.web.tsx

@@ -9,11 +9,10 @@ import React, {
   type ReactElement,
 } from 'react';
 
-import type { ViewStyle } from 'react-native';
-
 import { useTheme } from '../theme/use-theme';
 import type { Theme } from '../theme/types';
 import { SpinnerIcon } from '../loading/SpinnerIcon.web';
+import { flattenWebStyle } from '../styles/flatten-web-style';
 import type { ButtonProps, ButtonSize, ButtonVariant } from './types';
 
 export type { ButtonProps, ButtonVariant, ButtonSize } from './types';
@@ -218,37 +217,6 @@ function resolveVariantStyle(
   }
 }
 
-// ---------------------------------------------------------------------------
-//  Style normalization
-//
-//  Callers idiomatically pass `style` as a React-Native `StyleProp` — most
-//  often an ARRAY (`style={[base, cond && override]}`, possibly nested and
-//  containing falsy holes from `cond && {...}`). The DOM `<button>` below needs
-//  a SINGLE plain object: spreading a raw array into an object literal produces
-//  numeric keys (`"0"`, `"1"`, …), which React then assigns onto the real
-//  `CSSStyleDeclaration`, throwing
-//  `Failed to set an indexed property [0] on 'CSSStyleDeclaration'`. Flatten the
-//  StyleProp into one object here, once, before it reaches either merge site.
-//  Later entries win, mirroring React-Native array-style precedence.
-//
-//  `StyleNode` is a readonly-closed recursion type (RN's own `StyleProp` array
-//  member yields `readonly` sub-arrays that aren't assignable back to
-//  `StyleProp`, so it can't be recursed over directly). `ButtonProps['style']`
-//  is assignable to it, so call sites pass `style` with no cast.
-// ---------------------------------------------------------------------------
-
-type StyleNode = ViewStyle | false | null | undefined | '' | ReadonlyArray<StyleNode>;
-
-function flattenStyle(style: StyleNode): CSSProperties {
-  if (Array.isArray(style)) {
-    return style.reduce<CSSProperties>(
-      (merged, entry) => Object.assign(merged, flattenStyle(entry)),
-      {},
-    );
-  }
-  return style && typeof style === 'object' ? (style as CSSProperties) : {};
-}
-
 // ---------------------------------------------------------------------------
 //  Component
 // ---------------------------------------------------------------------------
@@ -350,9 +318,11 @@ const ButtonWebComponent: React.FC<ButtonProps> = ({
 
   const spinnerColor = loadingColor ?? variantStyle.textColor;
 
-  // Normalize the caller's `style` (single object, array, or falsy) into one
-  // flat plain object ONCE, so neither merge site below spreads a raw array.
-  const resolvedStyle = flattenStyle(style);
+  // Normalize the caller's `style` (single object, StyleProp array, or falsy)
+  // into ONE flat plain object here, once, so neither raw-DOM merge site below
+  // spreads a StyleProp array (which would leak numeric keys onto the button's
+  // CSSStyleDeclaration). See `flattenWebStyle` for the full rationale.
+  const resolvedStyle = flattenWebStyle(style);
 
   const content = (
     <>

package/src/fab/Fab.web.tsx

@@ -10,6 +10,7 @@ import React, {
 
 import { useTheme } from '../theme/use-theme';
 import type { Theme } from '../theme/types';
+import { flattenWebStyle } from '../styles/flatten-web-style';
 import type { FabPlacement, FabProps, FabSize, FabVariant } from './types';
 
 export type { FabProps, FabVariant, FabSize, FabPlacement } from './types';
@@ -261,12 +262,20 @@ const FabWebComponent: React.FC<FabProps> = ({
   const ariaLabel = ariaLabelProp ?? accessibilityLabel ?? label;
   const composedClassName = ['bloom-fab'].concat(className ? [className] : []).join(' ');
 
+  // Normalize `style`/`labelStyle` (single object, StyleProp array — the native
+  // fork passes `style={[placementStyle(...), {...}, style]}` — or falsy) into
+  // ONE flat plain object each, so neither raw-DOM merge site below spreads a
+  // StyleProp array (which would leak numeric keys onto the element's
+  // CSSStyleDeclaration). See `flattenWebStyle` for the full rationale.
+  const resolvedStyle = flattenWebStyle(style);
+  const resolvedLabelStyle = flattenWebStyle(labelStyle);
+
   return (
     <button
       id={resolvedId}
       type={type}
       className={composedClassName}
-      style={{ ...containerStyle, ...(style as CSSProperties) }}
+      style={{ ...containerStyle, ...resolvedStyle }}
       onClick={handleClick}
       disabled={disabled}
       aria-disabled={disabled || undefined}
@@ -288,7 +297,7 @@ const FabWebComponent: React.FC<FabProps> = ({
           {content}
         </span>
       )}
-      {isExtended && <span style={labelStyle as CSSProperties}>{label}</span>}
+      {isExtended && <span style={resolvedLabelStyle}>{label}</span>}
     </button>
   );
 };

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';

package/src/styles/flatten-web-style.ts

@@ -0,0 +1,58 @@
+import type { CSSProperties } from 'react';
+import type { TextStyle, ViewStyle } from 'react-native';
+
+// ---------------------------------------------------------------------------
+//  flattenWebStyle — StyleProp → plain CSSProperties, for raw-DOM web forks.
+//
+//  A handful of Bloom's `.web.tsx` forks (`Button.web.tsx`, `Fab.web.tsx`)
+//  render REAL HTML elements through react-dom (`<button>`, `<span>`), NOT
+//  react-native-web components. Their `style` prop is therefore a single plain
+//  `CSSProperties` object that React commits straight to a live
+//  `CSSStyleDeclaration`.
+//
+//  Callers, however, pass `style` as a React-Native `StyleProp` — most often an
+//  ARRAY (`style={[base, cond && override]}`, possibly nested, with falsy holes
+//  from `cond && {...}`). Spreading a raw array into an object literal produces
+//  numeric keys ("0", "1", …), which React then assigns onto the DOM node's
+//  `CSSStyleDeclaration`, throwing:
+//    `Failed to set an indexed property [0] on 'CSSStyleDeclaration'`.
+//
+//  Why NOT `StyleSheet.flatten` (the convention the RNW-component forks such as
+//  `list/index.web.tsx` use): these raw-DOM forks have NO other react-native
+//  runtime dependency. Reaching for `StyleSheet.flatten` would couple them to
+//  the `react-native` → `react-native-web` bundler alias they otherwise never
+//  need — a coupling the jsdom test environment does not provide (its
+//  `react-native` mock stubs `flatten` as an identity no-op, so an array would
+//  pass through unflattened and the raw-DOM render would crash under test). A
+//  dependency-free flatten is provably correct in every bundling/test context,
+//  so it is the right convention for THIS sub-class of forks specifically.
+//
+//  `StyleNode` is a readonly-closed recursion type: RN's own `StyleProp` array
+//  members are `readonly` and its `RegisteredStyle` members are branded numbers,
+//  neither of which is assignable back to `StyleProp` for direct recursion.
+//  `StyleProp<ViewStyle>` / `StyleProp<TextStyle>` ARE assignable to it, so call
+//  sites pass `style` / `labelStyle` with no cast. Later entries win, mirroring
+//  React-Native array-style precedence; falsy holes and unresolved registered-
+//  style ids (bare numbers — not resolvable without the RN runtime, and never
+//  passed to a raw-DOM fork in practice) are skipped.
+// ---------------------------------------------------------------------------
+
+type StyleNode =
+  | ViewStyle
+  | TextStyle
+  | number
+  | false
+  | null
+  | undefined
+  | ''
+  | ReadonlyArray<StyleNode>;
+
+export function flattenWebStyle(style: StyleNode): CSSProperties {
+  if (Array.isArray(style)) {
+    return style.reduce<CSSProperties>(
+      (merged, entry) => Object.assign(merged, flattenWebStyle(entry)),
+      {},
+    );
+  }
+  return style && typeof style === 'object' ? (style as CSSProperties) : {};
+}