@oneplatformdev/react-native-uikit 1.2.1 → 1.2.3

package/README.md

@@ -319,7 +319,16 @@ Owned source is available through `npx @oneplatformdev/react-native-uikit add sw
 
 ## PhotoPreview and EmptyListView
 
-`PhotoPreview` displays a supplied React Native image source. It defaults to a 120-unit square with the theme's medium radius. Set `width` and/or `height` for a different size; `aspectRatio` derives the missing dimension (width wins if both dimensions and a ratio are supplied). `style` is applied after the base container geometry, and `imageStyle` after the fill-image style. Supply `onPress` to make the image a button, `onRemovePress` for a separate remove control, or `overlay` for caller-owned content. A built-in × is used unless `removeIcon` is provided; supply localized accessibility labels for actions. The component does not open a modal or own image state.
+`PhotoPreview` uses `@d11/react-native-fast-image` for both the thumbnail and optional fullscreen viewer. Install that native peer in the app. It accepts a FastImage source (`{ uri }` or a local `require(...)`) and passes it unchanged to both images, preserving headers, priority, and any explicit cache policy. Without `source.cache`, FastImage uses its own default `immutable` policy (URI-keyed caching); choose `source={{ uri, cache: FastImage.cacheControl.web }}` when HTTP-header-aware caching is needed. The default thumbnail is a 120-unit square with the theme's medium radius. `width`/`height` are design values; `aspectRatio` derives the missing dimension (width wins if both dimensions and a ratio are supplied). `style` applies after container geometry; `imageStyle` applies after the fill-image style. Source, resize-mode, and image-style types follow FastImage rather than React Native `Image`.
+
+```tsx
+<PhotoPreview source={{ uri }} />
+<PhotoPreview source={{ uri }} fullscreen closeAccessibilityLabel={closePhotoLabel} />
+<PhotoPreview source={{ uri }} fullscreen closeIcon={<MyCloseIcon />} loadingIndicator={<MyLoader />} />
+<PhotoPreview source={{ uri }} onRemovePress={onRemove} removeIcon={<MyRemoveIcon />} />
+```
+
+`fullscreen` is opt-in. Pressing opens one built-in Modal with a cached FastImage (`contain` by default), a centered package Loader until load or error, and a close button positioned at the unscaled top safe-area inset plus scaled design spacing. Apps using fullscreen should configure their usual `SafeAreaProvider`. Override the fullscreen background, resize mode, image style, close icon/labels, or loading indicator as needed. With `fullscreen`, `onPress` observes the same thumbnail press after opening; `onFullscreenOpen`/`onFullscreenClose` observe viewer transitions. Without `fullscreen`, `onPress` keeps its prior behavior. The independent remove action never opens fullscreen; `overlay` remains thumbnail-only. A built-in × is used if `removeIcon` or `closeIcon` is omitted. Supply localized accessibility labels for actions.
 
 `EmptyListView` centers optional `visual`, `title`, and `description` in available list space. Strings and numbers use themed Typography (`title` and `body` by default); custom React nodes render as supplied. `titleStyle` and `descriptionStyle` apply to built-in text, while custom nodes own their styling. A supplied `action` replaces the built-in Button; otherwise the Button appears only when both `actionLabel` and `onActionPress` are given. The optional `accessibilityLabel` labels the visual without grouping the readable text or action.
 
@@ -337,7 +346,7 @@ Owned source is available with `npx @oneplatformdev/react-native-uikit add photo
 
 `BottomModal` provides the reference-style slide/drag dismissal and keyboard-height-aware positioning. Supply `children`, `onClose`, and optionally `title`, `customHeader`, and a labeled `closeAction` icon. `Keyboard.dismiss()` and the close animation start together; `closeRef` can trigger the same close path externally. The kit does not render app-specific toasts.
 
-Both modes require consumers to install the declared native peers used by these components: `react-native-keyboard-controller`, `react-native-linear-gradient`, `react-native-reanimated`, and `react-native-safe-area-context`. Applications using keyboard-aware or safe-area behavior should configure the providers and native setup required by those libraries. The kit does not bundle those peers or install them through `add`.
+Both modes require consumers to install the declared native peers used by these components: `@d11/react-native-fast-image`, `react-native-keyboard-controller`, `react-native-linear-gradient`, `react-native-reanimated`, and `react-native-safe-area-context`. Applications using keyboard-aware or safe-area behavior should configure the providers and native setup required by those libraries. The kit does not bundle those peers or install them through `add`.
 
 ## ConnectionContainer
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneplatformdev/react-native-uikit",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "bin": {
@@ -18,6 +18,7 @@
     "validate:registry": "node scripts/validate-registry.cjs"
   },
   "peerDependencies": {
+    "@d11/react-native-fast-image": "^8.13.0",
     "react": "*",
     "react-native": "*",
     "react-native-keyboard-controller": "^1.22.5",
@@ -26,6 +27,7 @@
     "react-native-safe-area-context": "^5.5.2"
   },
   "devDependencies": {
+    "@d11/react-native-fast-image": "^8.13.0",
     "@types/react": "^19.2.0",
     "react-native-keyboard-controller": "^1.22.5",
     "react-native-linear-gradient": "^2.8.3",

package/registry/manifest.json

@@ -58,10 +58,10 @@
   },
   "photo-preview": {
     "folder": "PhotoPreview",
-    "files": ["ui/PhotoPreview.tsx", "ui/styles.ts", "types/types.ts", "index.ts"],
-    "componentDependencies": [],
+    "files": ["ui/PhotoPreview.tsx", "presenters/usePhotoPreview.ts", "ui/styles.ts", "types/types.ts", "index.ts"],
+    "componentDependencies": ["loader"],
     "foundations": ["useUITheme", "useScaling", "UIColors", "UIRadius", "UISpacing", "ScalingFunctions"],
-    "dependencies": ["react", "react-native", "@oneplatformdev/react-native-uikit"],
+    "dependencies": ["react", "react-native", "@d11/react-native-fast-image", "react-native-safe-area-context", "@oneplatformdev/react-native-uikit"],
     "rewrites": {
       "../../../theme": "@oneplatformdev/react-native-uikit",
       "../../../utils": "@oneplatformdev/react-native-uikit"
@@ -148,6 +148,7 @@
     "folder": "Loader",
     "files": ["ui/Loader.tsx", "ui/styles.ts", "types/types.ts", "index.ts"],
     "componentDependencies": [],
+    "publicExports": { "Loader": "ui/Loader.tsx", "LoaderProps": "types/types.ts" },
     "foundations": ["useUITheme", "UIColors"],
     "dependencies": ["react", "react-native", "@oneplatformdev/react-native-uikit"],
     "rewrites": {

package/src/components/Loader/index.ts

@@ -1,2 +1,2 @@
-export { Loader } from './ui/Loader';
-export type { LoaderProps } from './types/types';
+export * from './ui/Loader';
+export * from './types/types';

package/src/components/PhotoPreview/presenters/usePhotoPreview.ts

@@ -0,0 +1,49 @@
+import { useCallback, useEffect, useState } from 'react';
+import type { PhotoPreviewProps } from '../types/types';
+
+export const usePhotoPreview = ({
+    fullscreen,
+    disabled,
+    onPress,
+    onFullscreenOpen,
+    onFullscreenClose,
+}: Pick<PhotoPreviewProps, 'fullscreen' | 'disabled' | 'onPress' | 'onFullscreenOpen' | 'onFullscreenClose'>) => {
+    const [visible, setVisible] = useState(false);
+
+    useEffect(() => {
+        if (!fullscreen) setVisible(false);
+    }, [fullscreen]);
+
+    const onThumbnailPress = useCallback(() => {
+        if (disabled) return;
+        if (fullscreen) {
+            setVisible(true);
+            onFullscreenOpen?.();
+        }
+        onPress?.();
+    }, [disabled, fullscreen, onFullscreenOpen, onPress]);
+
+    const onClose = useCallback(() => {
+        setVisible(false);
+        onFullscreenClose?.();
+    }, [onFullscreenClose]);
+
+    return { visible: fullscreen === true && visible, onThumbnailPress, onClose };
+};
+
+type LoadState = 'loading' | 'loaded' | 'error';
+
+export const useFullscreenImage = () => {
+    const [loadState, setLoadState] = useState<LoadState>('loading');
+    const onLoadStart = useCallback(() => setLoadState('loading'), []);
+    const onLoad = useCallback(() => setLoadState('loaded'), []);
+    const onError = useCallback(() => setLoadState('error'), []);
+
+    return {
+        isLoading: loadState === 'loading',
+        isImageVisible: loadState === 'loaded',
+        onLoadStart,
+        onLoad,
+        onError,
+    };
+};

package/src/components/PhotoPreview/types/types.ts

@@ -1,13 +1,24 @@
 import type { ReactNode } from 'react';
-import type { ImageResizeMode, ImageSourcePropType, ImageStyle, StyleProp, ViewStyle } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { FastImageProps } from '@d11/react-native-fast-image';
 
 export interface PhotoPreviewProps {
-    source: ImageSourcePropType;
+    source: NonNullable<FastImageProps['source']>;
     width?: number;
     height?: number;
     aspectRatio?: number;
     borderRadius?: number;
-    resizeMode?: ImageResizeMode;
+    resizeMode?: FastImageProps['resizeMode'];
+    fullscreen?: boolean;
+    fullscreenResizeMode?: FastImageProps['resizeMode'];
+    fullscreenBackgroundColor?: string;
+    fullscreenImageStyle?: FastImageProps['style'];
+    closeIcon?: ReactNode;
+    closeAccessibilityLabel?: string;
+    closeAccessibilityHint?: string;
+    loadingIndicator?: ReactNode;
+    onFullscreenOpen?: () => void;
+    onFullscreenClose?: () => void;
     overlay?: ReactNode;
     removeIcon?: ReactNode;
     onRemovePress?: () => void;
@@ -18,5 +29,5 @@ export interface PhotoPreviewProps {
     accessibilityHint?: string;
     disabled?: boolean;
     style?: StyleProp<ViewStyle>;
-    imageStyle?: StyleProp<ImageStyle>;
+    imageStyle?: FastImageProps['style'];
 }

package/src/components/PhotoPreview/ui/PhotoPreview.tsx

@@ -1,17 +1,118 @@
 import { useMemo } from 'react';
-import { Image, Pressable, StyleSheet, Text, View } from 'react-native';
+import { Modal, Pressable, StyleSheet, Text, View } from 'react-native';
+import { SafeAreaView, useSafeAreaInsets } from 'react-native-safe-area-context';
+import FastImage from '@d11/react-native-fast-image';
+import { Loader } from '../../Loader';
 import { useUITheme } from '../../../theme';
 import { useScaling } from '../../../utils';
-import { getStyles } from './styles';
+import { useFullscreenImage, usePhotoPreview } from '../presenters/usePhotoPreview';
+import { fastImageStyles, getFullscreenStyles, getStyles } from './styles';
 import type { PhotoPreviewProps } from '../types/types';
 
+type FullscreenImageProps = Pick<PhotoPreviewProps, 'source' | 'fullscreenResizeMode' | 'fullscreenImageStyle' | 'loadingIndicator'>
+    & { styles: ReturnType<typeof getFullscreenStyles>['styles'] };
+
+const FullscreenImage = ({ source, fullscreenResizeMode, fullscreenImageStyle, loadingIndicator, styles }: FullscreenImageProps) => {
+    const { isLoading, isImageVisible, onLoadStart, onLoad, onError } = useFullscreenImage();
+    const hasSource = typeof source === 'number' || Boolean(source.uri?.trim());
+
+    return (
+        <View style={styles.imageArea}>
+            {hasSource ? (
+                <FastImage
+                    source={source}
+                    resizeMode={fullscreenResizeMode ?? FastImage.resizeMode.contain}
+                    accessible={false}
+                    style={[fastImageStyles.fill, fullscreenImageStyle, !isImageVisible && fastImageStyles.hidden]}
+                    onLoadStart={onLoadStart}
+                    onLoad={onLoad}
+                    onError={onError}
+                />
+            ) : null}
+            {hasSource && isLoading ? (
+                <View pointerEvents="none" style={styles.loadingOverlay}>
+                    {loadingIndicator === undefined ? <Loader inline transparent accessibilityLabel="Loading photo" /> : loadingIndicator}
+                </View>
+            ) : null}
+        </View>
+    );
+};
+
+type FullscreenViewerProps = Pick<PhotoPreviewProps,
+    | 'source' | 'fullscreenResizeMode' | 'fullscreenBackgroundColor' | 'fullscreenImageStyle'
+    | 'closeIcon' | 'closeAccessibilityLabel' | 'closeAccessibilityHint' | 'loadingIndicator'>
+    & { visible: boolean; onClose: () => void };
+
+const FullscreenViewer = ({
+    source,
+    visible,
+    onClose,
+    fullscreenResizeMode,
+    fullscreenBackgroundColor,
+    fullscreenImageStyle,
+    closeIcon,
+    closeAccessibilityLabel,
+    closeAccessibilityHint,
+    loadingIndicator,
+}: FullscreenViewerProps) => {
+    const { colors, spacing } = useUITheme();
+    const scaling = useScaling();
+    const { top } = useSafeAreaInsets();
+    const { styles, closeHitSlop } = useMemo(
+        () => getFullscreenStyles(colors, spacing, scaling, top, fullscreenBackgroundColor),
+        [colors, spacing, scaling, top, fullscreenBackgroundColor],
+    );
+    const sourceKey = typeof source === 'number' ? `asset:${source}` : JSON.stringify(source);
+
+    return (
+        <Modal visible={visible} animationType="fade" statusBarTranslucent onRequestClose={onClose}>
+            <SafeAreaView edges={['left', 'right', 'bottom']} style={styles.fullscreen} accessibilityViewIsModal>
+                <View style={styles.toolbar}>
+                    <Pressable
+                        accessibilityRole="button"
+                        accessibilityLabel={closeAccessibilityLabel ?? 'Close photo'}
+                        accessibilityHint={closeAccessibilityHint}
+                        hitSlop={closeHitSlop}
+                        onPress={onClose}
+                        style={styles.close}
+                    >
+                        {closeIcon === undefined ? <Text style={styles.closeText}>×</Text>
+                            : typeof closeIcon === 'string' || typeof closeIcon === 'number'
+                                ? <Text style={styles.closeText}>{closeIcon}</Text> : closeIcon}
+                    </Pressable>
+                </View>
+                {visible ? (
+                    <FullscreenImage
+                        key={sourceKey}
+                        source={source}
+                        fullscreenResizeMode={fullscreenResizeMode}
+                        fullscreenImageStyle={fullscreenImageStyle}
+                        loadingIndicator={loadingIndicator}
+                        styles={styles}
+                    />
+                ) : null}
+            </SafeAreaView>
+        </Modal>
+    );
+};
+
 export const PhotoPreview = ({
     source,
     width,
     height,
     aspectRatio,
     borderRadius,
-    resizeMode = 'cover',
+    resizeMode = FastImage.resizeMode.cover,
+    fullscreen = false,
+    fullscreenResizeMode,
+    fullscreenBackgroundColor,
+    fullscreenImageStyle,
+    closeIcon,
+    closeAccessibilityLabel,
+    closeAccessibilityHint,
+    loadingIndicator,
+    onFullscreenOpen,
+    onFullscreenClose,
     overlay,
     removeIcon,
     onRemovePress,
@@ -30,28 +131,34 @@ export const PhotoPreview = ({
         () => getStyles(colors, radius, spacing, scaling, width, height, aspectRatio, borderRadius),
         [colors, radius, spacing, scaling, width, height, aspectRatio, borderRadius],
     );
+    const { visible, onThumbnailPress, onClose } = usePhotoPreview({
+        fullscreen, disabled, onPress, onFullscreenOpen, onFullscreenClose,
+    });
+    const isPressable = fullscreen || onPress !== undefined;
     const image = (
-        <Image
-            source={source}
-            resizeMode={resizeMode}
-            accessible={!onPress}
-            accessibilityRole={onPress ? undefined : 'image'}
-            accessibilityLabel={onPress ? undefined : accessibilityLabel}
-            accessibilityHint={onPress ? undefined : accessibilityHint}
-            style={[styles.image, imageStyle]}
-        />
+        <View style={styles.image}>
+            <FastImage
+                source={source}
+                resizeMode={resizeMode}
+                accessible={!isPressable}
+                accessibilityRole={isPressable ? undefined : 'image'}
+                accessibilityLabel={isPressable ? undefined : accessibilityLabel}
+                accessibilityHint={isPressable ? undefined : accessibilityHint}
+                style={[fastImageStyles.fill, imageStyle]}
+            />
+        </View>
     );
 
     return (
         <View style={[styles.container, style]}>
-            {onPress ? (
+            {isPressable ? (
                 <Pressable
                     accessibilityRole="button"
-                    accessibilityLabel={accessibilityLabel}
+                    accessibilityLabel={accessibilityLabel ?? 'Open photo'}
                     accessibilityHint={accessibilityHint}
                     accessibilityState={{ disabled }}
                     disabled={disabled}
-                    onPress={onPress}
+                    onPress={onThumbnailPress}
                     style={StyleSheet.absoluteFill}
                 >
                     {image}
@@ -78,6 +185,20 @@ export const PhotoPreview = ({
                             ? <Text style={styles.removeText}>{removeIcon}</Text> : removeIcon}
                 </Pressable>
             ) : null}
+            {fullscreen ? (
+                <FullscreenViewer
+                    source={source}
+                    visible={visible}
+                    onClose={onClose}
+                    fullscreenResizeMode={fullscreenResizeMode}
+                    fullscreenBackgroundColor={fullscreenBackgroundColor}
+                    fullscreenImageStyle={fullscreenImageStyle}
+                    closeIcon={closeIcon}
+                    closeAccessibilityLabel={closeAccessibilityLabel}
+                    closeAccessibilityHint={closeAccessibilityHint}
+                    loadingIndicator={loadingIndicator}
+                />
+            ) : null}
         </View>
     );
 };

package/src/components/PhotoPreview/ui/styles.ts

@@ -1,4 +1,6 @@
 import { StyleSheet } from 'react-native';
+import type { ViewStyle } from 'react-native';
+import type { ImageStyle as FastImageImageStyle } from '@d11/react-native-fast-image';
 import type { UIColors, UIRadius, UISpacing } from '../../../theme';
 import type { ScalingFunctions } from '../../../utils';
 import type { PhotoPreviewProps } from '../types/types';
@@ -6,6 +8,13 @@ import type { PhotoPreviewProps } from '../types/types';
 const positiveOrUndefined = (value: number | undefined) =>
     value !== undefined && Number.isFinite(value) && value > 0 ? value : undefined;
 
+type CompatibleFastImageStyle = FastImageImageStyle & Pick<ViewStyle, 'width' | 'height' | 'opacity'>;
+
+export const fastImageStyles: Record<'fill' | 'hidden', CompatibleFastImageStyle> = {
+    fill: { width: '100%', height: '100%' },
+    hidden: { opacity: 0 },
+};
+
 export const getStyles = (
     colors: UIColors,
     radius: UIRadius,
@@ -66,3 +75,45 @@ export const getStyles = (
 
     return { styles, removeHitSlop };
 };
+
+export const getFullscreenStyles = (
+    colors: UIColors,
+    spacing: UISpacing,
+    scaling: ScalingFunctions,
+    topInset: number,
+    backgroundColor?: string,
+) => {
+    const styles = StyleSheet.create({
+        fullscreen: {
+            flex: 1,
+            backgroundColor: backgroundColor ?? colors.text,
+        },
+        toolbar: {
+            alignItems: 'flex-end',
+            paddingHorizontal: scaling.scaleHorizontal(spacing.lg),
+            paddingTop: topInset + scaling.scaleVertical(spacing.sm),
+        },
+        close: {
+            width: scaling.scaleHorizontal(40),
+            height: scaling.scaleHorizontal(40),
+            alignItems: 'center',
+            justifyContent: 'center',
+        },
+        closeText: {
+            color: colors.onPrimary,
+            fontSize: scaling.scaleFontSize(24),
+            lineHeight: scaling.scaleLineHeight(28),
+        },
+        imageArea: {
+            flex: 1,
+            width: '100%',
+        },
+        loadingOverlay: {
+            ...StyleSheet.absoluteFill,
+            alignItems: 'center',
+            justifyContent: 'center',
+        },
+    });
+
+    return { styles, closeHitSlop: scaling.scaleHorizontal(spacing.xs) };
+};