@oneplatformdev/react-native-uikit 1.2.7 → 1.2.8

package/README.md

@@ -343,6 +343,20 @@ Owned source is available with `npx @oneplatformdev/react-native-uikit add photo
 
 `ScreenContainer` provides a theme-backed safe-area layout, optional scrolling, and optional keyboard-aware scrolling or avoidance. Pass `gradient={{ colors, locations, start, end }}` to render a caller-configured background across the entire screen, behind the safe-area content; omit it for the solid theme background. Gradient coordinates are normalized and are not scaled. Pass ordinary ScrollView props when scrolling is enabled; use `containerStyle` and `contentContainerStyle` for layout overrides.
 
+Pass `background={<DecorativeBackground />}` for an application-owned, full-screen layer behind the safe-area content. It replaces `gradient` when both are supplied, does not affect layout, and cannot intercept touches. Pass `overlay={<FloatingAction />}` for a full-screen layer above the content; empty parts of that layer pass touches through, while its interactive children remain usable. The consumer owns each overlay child's position, safe-area offsets, visibility, and interactions.
+
+For non-scrolling keyboard avoidance, omitting `keyboardAvoidingBehavior` keeps the default `behavior="padding"`; `keyboardAvoidingBehavior={null}` omits the behavior prop; an explicit behavior is forwarded. Keyboard-aware scrolling is unchanged.
+
+```tsx
+<ScreenContainer background={<DecorativeBackground />} overlay={<FloatingAction />}>
+  <Content />
+</ScreenContainer>
+
+<ScreenContainer isKeyboardAvoiding keyboardAvoidingBehavior={null}>
+  <Form />
+</ScreenContainer>
+```
+
 `CustomAlert` animates a centered modal with a dismissible backdrop. Supply `header`, children, and optional `footer` content; compose your own actions with `Button`. Optional `closeAction` accepts an icon and an application-supplied accessibility label. No strings are translated by the kit.
 
 `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneplatformdev/react-native-uikit",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "bin": {

package/src/components/ScreenContainer/types/types.ts

@@ -1,6 +1,6 @@
 import type { ComponentRef, ReactNode, Ref } from 'react';
 import type { ScrollView, ScrollViewProps, StyleProp, ViewStyle } from 'react-native';
-import type { KeyboardAwareScrollViewRef } from 'react-native-keyboard-controller';
+import type { KeyboardAwareScrollViewRef, KeyboardAvoidingViewProps } from 'react-native-keyboard-controller';
 import type { LinearGradientProps } from 'react-native-linear-gradient';
 import type { Edge } from 'react-native-safe-area-context';
 
@@ -14,7 +14,10 @@ export interface ScreenContainerProps extends Omit<ScrollViewProps, 'children' |
     contentContainerStyle?: StyleProp<ViewStyle>;
     headerComponent?: ReactNode;
     footerComponent?: ReactNode;
+    background?: ReactNode;
+    overlay?: ReactNode;
     scrollViewRef?: Ref<ComponentRef<typeof ScrollView>>;
     keyboardScrollViewRef?: Ref<KeyboardAwareScrollViewRef>;
+    keyboardAvoidingBehavior?: KeyboardAvoidingViewProps['behavior'] | null;
     gradient?: ScreenContainerGradient;
 }

package/src/components/ScreenContainer/ui/ScreenContainer.tsx

@@ -18,8 +18,11 @@ export const ScreenContainer = ({
     contentContainerStyle,
     headerComponent,
     footerComponent,
+    background,
+    overlay,
     scrollViewRef,
     keyboardScrollViewRef,
+    keyboardAvoidingBehavior,
     keyboardShouldPersistTaps = 'handled',
     showsVerticalScrollIndicator = false,
     gradient,
@@ -30,10 +33,17 @@ export const ScreenContainer = ({
     const styles = useMemo(() => getStyles(colors), [colors]);
     const bottomOffset = getBottomOffset(spacing, scaling);
     const { onContainerStartShouldSetResponder, onContainerResponderRelease } = useScreenContainer();
+    const keyboardAvoidingViewProps = keyboardAvoidingBehavior === null
+        ? {}
+        : { behavior: keyboardAvoidingBehavior ?? 'padding' };
 
     return (
         <View style={styles.root}>
-            {gradient ? <LinearGradient {...gradient} pointerEvents="none" style={styles.gradient} /> : null}
+            {background != null ? (
+                <View pointerEvents="none" style={styles.layer}>{background}</View>
+            ) : gradient ? (
+                <LinearGradient {...gradient} pointerEvents="none" style={styles.layer} />
+            ) : null}
             <SafeAreaView edges={edges} style={styles.safeArea}>
                 {headerComponent}
 
@@ -63,7 +73,7 @@ export const ScreenContainer = ({
                         </ScrollView>
                     )
                 ) : isKeyboardAvoiding ? (
-                    <KeyboardAvoidingView behavior="padding" style={[styles.container, containerStyle]}>
+                    <KeyboardAvoidingView {...keyboardAvoidingViewProps} style={[styles.container, containerStyle]}>
                         <View
                             style={styles.container}
                             onStartShouldSetResponder={onContainerStartShouldSetResponder}
@@ -78,6 +88,9 @@ export const ScreenContainer = ({
 
                 {footerComponent}
             </SafeAreaView>
+            {overlay != null ? (
+                <View pointerEvents="box-none" style={styles.layer}>{overlay}</View>
+            ) : null}
         </View>
     );
 };

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

@@ -9,7 +9,7 @@ export const getStyles = (colors: UIColors) => {
             flex: 1,
             backgroundColor: colors.background,
         },
-        gradient: {
+        layer: {
             position: 'absolute',
             top: 0,
             right: 0,