feat: add storybookUIVisibility and layout parameter (#815)

* feat: add fullscreenDefaultValue support and improve keyboard handling in layout components

* docs: add UI-related parameters for React Native Storybook, including fullscreen and safe area options

* fix: formatting

* use layout effect

* feat: layout parameter and updated ui visiblity param

* docs: update Storybook parameters for UI visibility and layout options

Author: dannyhw

docs/docs/intro/configuration/index.md

@@ -60,18 +60,10 @@ The `preview.tsx` file configures the story rendering environment and global par
 
 ```typescript
 import { Preview } from '@storybook/react-native';
-import { View } from 'react-native';
 import { withBackgrounds } from '@storybook/addon-ondevice-backgrounds';
 
 const preview: Preview = {
   decorators: [
-    // Global wrapper for all stories
-    (Story) => (
-      <View style={{ padding: 8 }}>
-        <Story />
-      </View>
-    ),
-
     // backgrounds addon decorator
     withBackgrounds,
   ],
@@ -89,6 +81,8 @@ const preview: Preview = {
     // UI Configuration
     hideFullScreenButton: false,
     noSafeArea: false,
+    storybookUIVisibility: 'visible', // 'visible' | 'hidden'
+    layout: 'padded', // 'fullscreen' | 'centered' | 'padded'
 
     // Background Configuration
     backgrounds: {
@@ -114,6 +108,8 @@ Other than story sort the other parameters can be overwritten per story.
 - `parameters.options.storySort`: Story sorting configuration
 - `parameters.hideFullScreenButton`: Toggle fullscreen button visibility
 - `parameters.noSafeArea`: Disable safe area insets
+- `parameters.storybookUIVisibility`: Controls UI visibility (`'visible'` | `'hidden'`)
+- `parameters.layout`: Controls story container layout (`'fullscreen'` | `'centered'` | `'padded'`)
 - `parameters.backgrounds`: Background addon configuration
 
 ## index.tsx

docs/docs/intro/writing-stories.md

@@ -133,6 +133,61 @@ export default meta;
 
 This parameter would instruct the backgrounds addon to reconfigure itself whenever a Button story is selected. Most addons are configured via a parameter-based API and can be influenced at a global, component and story level.
 
+#### UI-related parameters
+
+React Native Storybook provides several built-in parameters to control the on-device UI behavior:
+
+| Parameter               | Type                                         | Description                                                                                                                                       |
+| ----------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `noSafeArea`            | `boolean`                                    | When `true`, removes the top safe area padding, allowing your story to render edge-to-edge                                                        |
+| `storybookUIVisibility` | `'visible'` \| `'hidden'`                    | Controls the initial visibility of the Storybook UI. When `'hidden'`, the story starts in fullscreen mode                                         |
+| `hideFullScreenButton`  | `boolean`                                    | When `true`, hides the fullscreen toggle button                                                                                                   |
+| `layout`                | `'padded'` \| `'centered'` \| `'fullscreen'` | Controls the layout of the story container. `'padded'` adds padding, `'centered'` centers the content, `'fullscreen'` removes any default spacing |
+
+```tsx
+// Button.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react-native';
+
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+// Story that starts with the UI hidden
+export const UIHidden: Story = {
+  args: {
+    label: 'Button',
+  },
+  parameters: {
+    storybookUIVisibility: 'hidden',
+  },
+};
+
+// Story with centered layout
+export const Centered: Story = {
+  args: {
+    label: 'Button',
+  },
+  parameters: {
+    layout: 'centered',
+  },
+};
+
+// Story without safe area padding (edge-to-edge)
+export const EdgeToEdge: Story = {
+  args: {
+    label: 'Button',
+  },
+  parameters: {
+    noSafeArea: true,
+  },
+};
+```
+
 ### Using decorators
 
 Decorators are a mechanism to wrap a component in arbitrary markup when rendering a story. Components are often created with assumptions about ‘where’ they render. Your styles might expect a theme or layout wrapper, or your UI might expect specific context or data providers.

examples/expo-example/.rnstorybook/preview.tsx

@@ -1,16 +1,9 @@
-import { View, Appearance } from 'react-native';
+import { Appearance } from 'react-native';
 import { withBackgrounds } from '@storybook/addon-ondevice-backgrounds';
 import type { Preview } from '@storybook/react-native';
 
 const preview: Preview = {
-  decorators: [
-    (Story) => (
-      <View style={{ padding: 8, flex: 1 }}>
-        <Story />
-      </View>
-    ),
-    withBackgrounds,
-  ],
+  decorators: [withBackgrounds],
   parameters: {
     actions: { argTypesRegex: '^on[A-Z].*' },
     controls: {
@@ -29,6 +22,8 @@ const preview: Preview = {
     hideFullScreenButton: false,
     noSafeArea: false,
     my_param: 'anything',
+    layout: 'padded', // fullscreen, centered, padded
+    storybookUIVisibility: 'visible', // visible, hidden
     backgrounds: {
       default: Appearance.getColorScheme() === 'dark' ? 'dark' : 'plain',
       values: [

examples/expo-example/components/ControlExamples/Array/Array.stories.tsx

@@ -17,6 +17,8 @@ const meta = {
     notes: `
 This is actually not a proper control type and should be inferred from the object type but is currently an inconsistency in the rn addon.
     `,
+    storybookUIVisibility: 'hidden', // visible, hidden
+    layout: 'centered', // fullscreen, centered, padded
   },
 } satisfies Meta<typeof Array>;
 

packages/react-native-ui-lite/src/Layout.tsx

@@ -10,7 +10,7 @@ import {
   useStoreBooleanState,
   useStyle,
 } from '@storybook/react-native-ui-common';
-import { ReactElement, ReactNode, useCallback, useRef, useState } from 'react';
+import { ReactElement, ReactNode, useCallback, useLayoutEffect, useRef, useState } from 'react';
 import { ScrollView, Text, TouchableOpacity, View, ViewStyle } from 'react-native';
 import { SafeAreaProvider, useSafeAreaInsets } from 'react-native-safe-area-context';
 import { SET_CURRENT_STORY } from 'storybook/internal/core-events';
@@ -102,6 +102,10 @@ export const Layout = ({
 
   const [uiHidden, setUiHidden] = useState(false);
 
+  useLayoutEffect(() => {
+    setUiHidden(story?.parameters?.storybookUIVisibility === 'hidden');
+  }, [story?.parameters?.storybookUIVisibility]);
+
   const desktopSidebarStyle = useStyle(
     () => ({
       width: desktopSidebarOpen ? 240 : undefined,

packages/react-native-ui-lite/src/MobileAddonsPanel.tsx

@@ -167,6 +167,7 @@ export const MobileAddonsPanel = forwardRef<MobileAddonsPanelRef, { storyId?: st
             <AddonsTabs
               onClose={() => {
                 setMobileMenuOpen(false);
+                Keyboard.dismiss();
               }}
               storyId={storyId}
             />
@@ -250,6 +251,7 @@ export const AddonsTabs = ({ onClose, storyId }: { onClose?: () => void; storyId
           horizontal
           showsHorizontalScrollIndicator={false}
           contentContainerStyle={addonsTabsContentContainerStyle}
+          keyboardShouldPersistTaps="handled"
         >
           {Object.values(panels).map(({ id, title }) => {
             const resolvedTitle = typeof title === 'function' ? title({}) : title;

packages/react-native-ui/src/Layout.tsx

@@ -1,5 +1,5 @@
 import { BottomSheetModalProvider } from '@gorhom/bottom-sheet';
-import { PortalHost, PortalProvider } from '@gorhom/portal';
+import { PortalHost } from '@gorhom/portal';
 import type { ReactRenderer } from '@storybook/react';
 import { styled, ThemeProvider, useTheme } from '@storybook/react-native-theming';
 import {
@@ -11,7 +11,7 @@ import {
   useStyle,
   type SBUI,
 } from '@storybook/react-native-ui-common';
-import { ReactNode, useCallback, useRef, useState } from 'react';
+import { ReactNode, useCallback, useLayoutEffect, useRef, useState } from 'react';
 import { ScrollView, Text, TouchableOpacity, View, ViewStyle } from 'react-native';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import { SafeAreaProvider, useSafeAreaInsets } from 'react-native-safe-area-context';
@@ -108,6 +108,10 @@ export const Layout = ({
 
   const [uiHidden, setUiHidden] = useState(false);
 
+  useLayoutEffect(() => {
+    setUiHidden(story?.parameters?.storybookUIVisibility === 'hidden');
+  }, [story?.id, story?.parameters?.storybookUIVisibility]);
+
   const desktopSidebarStyle = useStyle(
     () => ({
       width: desktopSidebarOpen ? 240 : undefined,

packages/react-native/src/components/StoryView/StoryView.tsx

@@ -32,6 +32,12 @@ const errorContainerStyle = {
   justifyContent: 'center',
 } satisfies ViewStyle;
 
+const layoutStyles = {
+  padded: { padding: 8 },
+  centered: { alignItems: 'center', justifyContent: 'center' },
+  fullscreen: {},
+} satisfies Record<string, ViewStyle>;
+
 const StoryView = ({ useWrapper = true }: { useWrapper?: boolean }) => {
   const context = useStoryContext();
 
@@ -40,12 +46,15 @@ const StoryView = ({ useWrapper = true }: { useWrapper?: boolean }) => {
   const theme = useTheme();
 
   const containerStyle = useMemo(() => {
+    const layout = context?.parameters?.layout;
+    const layoutStyle = layout ? layoutStyles[layout] : {};
     return {
       flex: 1,
       backgroundColor: theme.background?.content,
       overflow: 'hidden',
+      ...layoutStyle,
     } satisfies ViewStyle;
-  }, [theme.background?.content]);
+  }, [theme.background?.content, context?.parameters?.layout]);
 
   const onError = useCallback(() => {
     console.log(`Error rendering story for ${context?.title} ${context?.name}`);
@@ -80,7 +89,7 @@ const StoryView = ({ useWrapper = true }: { useWrapper?: boolean }) => {
 
   return (
     <View style={errorContainerStyle}>
-      <Text>Please open the sidebar and select a story to preview.</Text>
+      <Text>Please select a story to preview.</Text>
     </View>
   );
 };