@multiplatform.one/components 7.4.1 → 7.5.0

package/src/layouts/Breadcrumbs.stories.tsx

@@ -1,11 +1,23 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { YStack } from "tamagui";
 import { Breadcrumbs } from "./breadcrumbs";
 
-export default {
+const meta: Meta<typeof Breadcrumbs> = {
   title: "Components/Breadcrumbs",
   component: Breadcrumbs,
-  parameters: { status: { type: "stable" } },
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "Wayfinding trail: landmark nav, last crumb is the current page. Tight chromeless gap (LC-03). Crumb labels are weight 400 (R7).",
+      },
+    },
+  },
 };
+export default meta;
+
+type Story = StoryObj<typeof Breadcrumbs>;
 
 const deepItems = [
   { label: "Home", href: "/" },
@@ -17,32 +29,36 @@ const deepItems = [
   { label: "Settings" },
 ];
 
-export const Default = () => (
-  <YStack gap="$4" padding="$4">
-    <Breadcrumbs
-      items={[
-        { label: "Home", href: "/" },
-        { label: "Projects", href: "/projects" },
-        { label: "multiplatform.one", href: "/projects/mp1" },
-        { label: "Settings" },
-      ]}
-      onNavigate={(href) => console.log("Navigate:", href)}
-    />
-    <Breadcrumbs
-      items={[{ label: "Dashboard", href: "/" }, { label: "Users" }]}
-      onNavigate={(href) => console.log("Navigate:", href)}
-    />
-  </YStack>
-);
-Default.storyName = "Main";
+export const Default: Story = {
+  name: "Main",
+  render: () => (
+    <YStack gap="$4" padding="$4">
+      <Breadcrumbs
+        items={[
+          { label: "Home", href: "/" },
+          { label: "Projects", href: "/projects" },
+          { label: "multiplatform.one", href: "/projects/mp1" },
+          { label: "Settings" },
+        ]}
+        onNavigate={(href) => console.log("Navigate:", href)}
+      />
+      <Breadcrumbs
+        items={[{ label: "Dashboard", href: "/" }, { label: "Users" }]}
+        onNavigate={(href) => console.log("Navigate:", href)}
+      />
+    </YStack>
+  ),
+};
 
-export const Overflow = () => (
-  <YStack gap="$4" maxWidth={480} padding="$4">
-    <Breadcrumbs
-      items={deepItems}
-      maxVisible={4}
-      onNavigate={(href) => console.log("Navigate:", href)}
-    />
-  </YStack>
-);
-Overflow.storyName = "Overflow";
+export const Overflow: Story = {
+  name: "Overflow",
+  render: () => (
+    <YStack gap="$4" maxWidth={480} padding="$4">
+      <Breadcrumbs
+        items={deepItems}
+        maxVisible={4}
+        onNavigate={(href) => console.log("Navigate:", href)}
+      />
+    </YStack>
+  ),
+};

package/src/layouts/Debug/DebugLayout.stories.tsx

@@ -1,19 +1,93 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { action } from "@multiplatform.one/storybook";
 import { Button } from "@multiplatform.one/forms";
-import { withDebugLayout } from "./index";
+import { Paragraph, YStack } from "tamagui";
+import { DebugLayout, createWithDebugLayout } from "./index";
 
-export default {
+function DebugRows() {
+  return <Paragraph>scheme / knobs / env</Paragraph>;
+}
+
+const meta: Meta<typeof DebugLayout> = {
   title: "Components/DebugLayout",
+  component: DebugLayout,
   parameters: {
     status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "Diagnostic overlay: a corner pip (R-PILL) opens a house PopoverContent of debug rows. Off unless DEBUG=1 or `enabled`. The overlay is pointer-events box-none so children keep their hits except on the pip itself.",
+      },
+    },
+  },
+  argTypes: {
+    enabled: { control: "boolean" },
+    size: { control: "number" },
+  },
+  args: {
+    enabled: true,
   },
 };
+export default meta;
 
-const MainComponent = withDebugLayout(() => (
-  <Button onPress={action("onPress")}>Hello, world!</Button>
-));
+type Story = StoryObj<typeof DebugLayout>;
 
-export const main = {
+export const Default: Story = {
   name: "Main",
-  render: () => <MainComponent />,
+  render: (args) => (
+    <YStack minHeight={240} width="100%" backgroundColor="$background" padding="$4">
+      <DebugLayout {...args} debugView={DebugRows}>
+        <Button alignSelf="flex-start" onPress={action("onPress")}>
+          Hello, world!
+        </Button>
+      </DebugLayout>
+    </YStack>
+  ),
+};
+
+export const EmptyChildren: Story = {
+  render: (args) => (
+    <YStack minHeight={160} width="100%" padding="$4">
+      <DebugLayout {...args} debugView={DebugRows} />
+    </YStack>
+  ),
+};
+
+export const Nested: Story = {
+  render: (args) => (
+    <YStack minHeight={240} width="100%" padding="$4">
+      <DebugLayout {...args} debugView={DebugRows}>
+        <YStack gap="$3">
+          <Paragraph>Outer layout</Paragraph>
+          <Button alignSelf="flex-start">Nested child</Button>
+        </YStack>
+      </DebugLayout>
+    </YStack>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { enabled: false },
+  render: (args) => (
+    <YStack minHeight={160} padding="$4">
+      <DebugLayout {...args}>
+        <Button alignSelf="flex-start">No debug chrome</Button>
+      </DebugLayout>
+    </YStack>
+  ),
+};
+
+const HocPage = createWithDebugLayout([], { enabled: true, debugView: DebugRows })(() => (
+  <Button alignSelf="flex-start" onPress={action("onHocPress")}>
+    HOC child
+  </Button>
+));
+
+export const WithHoc: Story = {
+  name: "withDebugLayout",
+  render: () => (
+    <YStack minHeight={160} padding="$4">
+      <HocPage />
+    </YStack>
+  ),
 };

package/src/layouts/Debug/debug.spec.tsx

@@ -12,67 +12,11 @@ vi.mock("multiplatform.one", () => ({
   isWeb: false,
 }));
 
-vi.mock("@multiplatform.one/platform", () => ({
-  config: { get: () => "1" },
-  createWithLayout: vi.fn((Component: any) => Component),
-}));
-
-vi.mock("@multiplatform.one/theme", () => {
-  // Mirrors the resolveKnobs output for default (medium) knobs; this spec-level
-  // mock shadows the test-utils setup mock, so it must carry the full shape.
-  const stateRecipe = {
-    hoverKnobProps: undefined,
-    pressKnobProps: undefined,
-    focusKnobProps: undefined,
-    focusVisibleKnobProps: undefined,
-  };
-  const knobProps = {
-    borderRadius: { borderRadius: "$4", borderColor: "$borderColor", borderWidth: 1 },
-    borderRadiusOuter: { borderRadius: "$3" },
-    elevation: "$2",
-    surface: { backgroundColor: "$color1", borderColor: "$borderColor", borderWidth: 1 },
-    cardSurface: { backgroundColor: "$color1", borderRadius: "$4", padding: "$4" },
-    elevatedSurface: {
-      backgroundColor: "$color1",
-      borderColor: "$borderColor",
-      borderWidth: 1,
-      borderRadius: "$4",
-      elevation: "$2",
-    },
-    featureSurface: {
-      backgroundColor: "$color1",
-      borderRadius: "$10",
-      padding: "$6",
-      shadowColor: "rgba(0,0,0,0.02)",
-      shadowOffset: { width: 0, height: 9 },
-      shadowOpacity: 1,
-      shadowRadius: 12,
-    },
-    inputSurface: { borderWidth: 1 },
-    panelPadding: { padding: "$4" },
-    gap: { gap: "$4" },
-    gapLg: { gap: "$5" },
-    sizeToken: "$4",
-    heading: { fontFamily: "$heading", fontWeight: "400" },
-    body: { fontFamily: "$body", fontWeight: "400" },
-    textWeight: { fontWeight: "400" },
-    transition: "quick",
-    outlined: false,
-    pointy: false,
-    textAccent: "high",
-    textAccentColor: "$color",
-    inputBackground: "$color2",
-    space: "medium",
-    size: "medium",
-  };
+vi.mock("@multiplatform.one/platform", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@multiplatform.one/platform")>();
   return {
-    useTheme: () => [{}, vi.fn(), false],
-    useResolvedKnobs: () => ({
-      knobProps,
-      control: { ...stateRecipe },
-      text: { ...stateRecipe },
-      elevation: { ...stateRecipe },
-    }),
+    ...actual,
+    config: { get: () => "1" },
   };
 });
 
@@ -243,6 +187,39 @@ describe("DebugLayout", () => {
     expect(screen.getByTestId("debug-circle")).toBeTruthy();
   });
 
+  it("hides the pip when enabled is false", () => {
+    renderWithProviders(
+      <DebugLayout enabled={false}>
+        <Paragraph data-testid="child">Hidden chrome</Paragraph>
+      </DebugLayout>,
+    );
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+    expect(screen.queryByTestId("debug-circle")).not.toBeInTheDocument();
+  });
+
+  it("shows the pip when enabled is true even if the env gate is off", () => {
+    renderWithProviders(
+      <DebugLayout enabled>
+        <Paragraph>Forced chrome</Paragraph>
+      </DebugLayout>,
+    );
+    const pip = screen.getByTestId("debug-circle");
+    expect(pip).toBeInTheDocument();
+    expect(pip).toHaveAttribute("data-radius-class", "R-PILL");
+    expect(pip).toHaveAttribute("data-radius-part", "debug pip");
+  });
+
+  it("keeps children mounted under the overlay", () => {
+    renderWithProviders(
+      <DebugLayout enabled>
+        <Paragraph data-testid="child">Underlay</Paragraph>
+      </DebugLayout>,
+    );
+    expect(screen.getByTestId("debug-layout-root")).toBeInTheDocument();
+    expect(screen.getByTestId("child")).toBeInTheDocument();
+    expect(screen.getByTestId("debug-circle")).toBeInTheDocument();
+  });
+
   it.skip("should open popover when debug button is clicked", async () => {
     renderWithProviders(
       <DebugLayout>

package/src/layouts/Debug/index.tsx

@@ -2,63 +2,73 @@ import { componentColors } from "../../componentColors";
 import type { WithLayout } from "@multiplatform.one/platform";
 import { createWithLayout } from "@multiplatform.one/platform";
 import { config } from "@multiplatform.one/platform";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { OVERLAY_ANCHOR_GAP, radiusClassProps, useResolvedKnobs } from "@multiplatform.one/theme";
 import type { ComponentType, ReactNode } from "react";
 import { Circle, Popover, XStack, YStack } from "tamagui";
+import { PopoverContent } from "../../surfaces";
+
+const pipShape = radiusClassProps("R-PILL", "debug pip");
 
 export interface DebugLayoutProps<DebugViewProps> {
-  children: ReactNode;
+  children?: ReactNode;
   debugView?: ComponentType<DebugViewProps>;
   debugViewProps?: DebugViewProps;
+  /** Visual pip size. Defaults to the size-knob nested-control metric. */
   size?: number;
+  /**
+   * When set, overrides the `DEBUG=1` env gate. Stories pass `true` so the
+   * chrome is actually on screen (LC-56). Production omits it.
+   */
+  enabled?: boolean;
 }
 
 export function DebugLayout<DebugViewProps>({
   children,
   debugView,
   debugViewProps,
-  size = 12,
+  size,
+  enabled,
 }: DebugLayoutProps<DebugViewProps>) {
-  const { knobProps } = useResolvedKnobs();
+  const { knobProps } = useResolvedKnobs({ component: "DebugLayout" });
   const DebugView = debugView;
+  const show = enabled ?? config.get("DEBUG") === "1";
+  const pipSize = size ?? knobProps.nestedControl.px;
 
-  function renderDebug() {
-    return (
-      <XStack
-        {...knobProps.gap}
-        margin={knobProps.panelPadding.padding}
-        width={size}
-        height={size}
-        data-testid="debug-container"
-      >
-        <Popover placement="right" size="$5">
-          <Popover.Trigger>
-            <Circle
-              cursor="pointer"
-              backgroundColor={componentColors.debug}
-              width={size}
-              height={size}
-              data-testid="debug-circle"
-            />
-          </Popover.Trigger>
-          <Popover.Content
-            borderWidth={1}
-            borderColor="$borderColor"
-            elevation={knobProps.elevation}
-          >
-            <XStack {...knobProps.gap} />
-            {DebugView && <DebugView {...(debugViewProps as any)} />}
-          </Popover.Content>
-        </Popover>
-      </XStack>
-    );
-  }
+  if (!show) return <>{children}</>;
 
-  if (config.get("DEBUG") !== "1") return <>{children}</>;
   return (
-    <YStack fullscreen data-testid="debug-layout-root">
+    <YStack fullscreen pointerEvents="box-none" data-testid="debug-layout-root">
       {children}
-      <YStack position="absolute">{renderDebug()}</YStack>
+      <YStack
+        position="absolute"
+        top={0}
+        insetInlineEnd={0}
+        pointerEvents="box-none"
+        zIndex={1}
+        {...knobProps.panelPadding}
+      >
+        <XStack data-testid="debug-container" pointerEvents="auto">
+          <Popover placement="bottom" offset={OVERLAY_ANCHOR_GAP}>
+            <Popover.Trigger>
+              <Circle
+                {...pipShape}
+                cursor="pointer"
+                backgroundColor={componentColors.debug}
+                width={pipSize}
+                height={pipSize}
+                hitSlop={knobProps.nestedControl.hitSlop}
+                data-testid="debug-circle"
+                transition={knobProps.transition}
+              />
+            </Popover.Trigger>
+            <PopoverContent>
+              <YStack {...knobProps.panelPadding} {...knobProps.gap} {...knobProps.body}>
+                {DebugView ? <DebugView {...(debugViewProps as any)} /> : null}
+              </YStack>
+            </PopoverContent>
+          </Popover>
+        </XStack>
+      </YStack>
     </YStack>
   );
 }
@@ -79,4 +89,6 @@ export const withDebugLayout = createWithDebugLayout();
 interface CreateWithDebugLayout<DebugViewProps> {
   debugView?: ComponentType<DebugViewProps>;
   debugViewProps?: DebugViewProps;
+  enabled?: boolean;
+  size?: number;
 }

package/src/layouts/EmptyState.spec.tsx

@@ -0,0 +1,30 @@
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it } from "vitest";
+import { EmptyState } from "./EmptyState";
+
+describe("EmptyState", () => {
+  it("does not pin compact, so the density knob restyles the frame", () => {
+    const { container } = renderWithProviders(<EmptyState title="Create your first record" />);
+    const frame = container.querySelector("[data-empty-intent]") as HTMLElement;
+    expect(frame).toBeTruthy();
+    expect(frame.getAttribute("data-density")).toBeTruthy();
+    expect(frame.getAttribute("data-density")).not.toBe("");
+  });
+
+  it("publishes compact density when compact is set", () => {
+    const { container } = renderWithProviders(<EmptyState compact title="No matching records" />);
+    const frame = container.querySelector("[data-empty-intent]") as HTMLElement;
+    expect(frame.getAttribute("data-density")).toBe("compact");
+  });
+
+  it("renders the title as a heading on the full-page frame", () => {
+    const { container } = renderWithProviders(
+      <EmptyState
+        title="Create your first record"
+        description="Records you add will show up here."
+      />,
+    );
+    expect(container.querySelector("h2")?.textContent).toBe("Create your first record");
+    expect(container.textContent).toContain("Records you add will show up here.");
+  });
+});

package/src/layouts/EmptyState.tsx

@@ -46,14 +46,16 @@ export function EmptyState({
   description,
   icon,
   action,
-  compact = false,
+  compact,
   intent = "neutral",
   children,
   ...rest
 }: EmptyStateProps) {
-  // compact steps the resolved size/space knobs down one level, so the
-  // icon well, gaps, and copy shrink through the one pipeline (Axiom 5).
-  const { knobProps } = useResolvedKnobs({ compact });
+  // LC-76: compact is a density override (space only), not a size step.
+  // Omit it so the density knob can restyle pad/gap (Alert gallery hole).
+  const { knobProps } = useResolvedKnobs(
+    compact === undefined ? { component: "EmptyState" } : { component: "EmptyState", compact },
+  );
   // See PageHeader: native-only heading family from the headingFont knob.
   const headingFamily = isWeb ? null : { fontFamily: knobProps.heading.fontFamily };
   const titleId = useId();
@@ -101,6 +103,7 @@ export function EmptyState({
   ) : (
     <H2
       {...(isWeb ? { id: titleId } : { nativeID: titleId })}
+      {...knobProps.heading}
       {...headingFamily}
       {...knobProps.textWeight}
       textAlign="center"
@@ -120,6 +123,7 @@ export function EmptyState({
       alignItems="center"
       justifyContent="center"
       data-empty-intent={intent}
+      data-density={knobProps.density}
       {...(isWeb
         ? {
             role: isError ? "alert" : "status",

package/src/layouts/KeyboardAvoidingWrapper/KeyboardAvoidingWrapper.spec.tsx

@@ -0,0 +1,50 @@
+import { cleanup } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveKeyboardAvoidingBehavior } from "./behavior";
+import { KeyboardAvoidingWrapper } from "./index";
+
+afterEach(cleanup);
+
+describe("resolveKeyboardAvoidingBehavior", () => {
+  it("defaults to padding on iOS and height elsewhere", () => {
+    expect(resolveKeyboardAvoidingBehavior("ios")).toBe("padding");
+    expect(resolveKeyboardAvoidingBehavior("android")).toBe("height");
+    expect(resolveKeyboardAvoidingBehavior("web")).toBe("height");
+  });
+
+  it("an explicit behavior always wins", () => {
+    expect(resolveKeyboardAvoidingBehavior("ios", "position")).toBe("position");
+    expect(resolveKeyboardAvoidingBehavior("android", "padding")).toBe("padding");
+  });
+});
+
+describe("KeyboardAvoidingWrapper web", () => {
+  it("is a passthrough that still renders children", () => {
+    const { container } = renderWithProviders(
+      <KeyboardAvoidingWrapper behavior="padding" keyboardVerticalOffset={24}>
+        <span>Field</span>
+      </KeyboardAvoidingWrapper>,
+    );
+    const frame = container.querySelector(
+      '[data-testid="keyboard-avoiding-wrapper"]',
+    ) as HTMLElement;
+    expect(frame).toBeTruthy();
+    expect(frame.getAttribute("data-keyboard-avoiding")).toBe("web");
+    expect(frame.getAttribute("data-enabled")).toBe("true");
+    expect(frame.textContent).toContain("Field");
+  });
+
+  it("enabled=false still renders children on web", () => {
+    const { container } = renderWithProviders(
+      <KeyboardAvoidingWrapper enabled={false}>
+        <span>Still visible</span>
+      </KeyboardAvoidingWrapper>,
+    );
+    const frame = container.querySelector(
+      '[data-testid="keyboard-avoiding-wrapper"]',
+    ) as HTMLElement;
+    expect(frame.getAttribute("data-enabled")).toBe("false");
+    expect(frame.textContent).toContain("Still visible");
+  });
+});

package/src/layouts/KeyboardAvoidingWrapper/KeyboardAvoidingWrapper.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { Input } from "@multiplatform.one/forms";
-import { Text, YStack } from "tamagui";
+import { Paragraph, YStack } from "tamagui";
+import { componentColors } from "../../componentColors";
 import { KeyboardAvoidingWrapper } from "./index";
 
 const meta: Meta<typeof KeyboardAvoidingWrapper> = {
@@ -8,6 +9,12 @@ const meta: Meta<typeof KeyboardAvoidingWrapper> = {
   component: KeyboardAvoidingWrapper,
   parameters: {
     status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "Platform keyboard wrapper. Native shifts content when the keyboard appears; web is a passthrough. No owned surface — knobs must not change keyboard offset.",
+      },
+    },
   },
 };
 
@@ -17,15 +24,27 @@ type Story = StoryObj<typeof KeyboardAvoidingWrapper>;
 export const Default: Story = {
   name: "Main",
   render: () => (
-    <KeyboardAvoidingWrapper behavior="padding" padding="$4">
-      <YStack gap="$4">
-        <Text>Content inside KeyboardAvoidingWrapper</Text>
-        <Text fontSize="$2" color="$color10">
+    <KeyboardAvoidingWrapper>
+      <YStack>
+        <Paragraph>Content inside KeyboardAvoidingWrapper</Paragraph>
+        <Paragraph color={componentColors.text.muted}>
           On native, this shifts content when the keyboard appears. On web, it is a simple
           passthrough wrapper.
-        </Text>
+        </Paragraph>
         <Input label="Test input" placeholder="Focus to test keyboard avoidance" />
       </YStack>
     </KeyboardAvoidingWrapper>
   ),
 };
+
+export const Empty: Story = {
+  render: () => <KeyboardAvoidingWrapper />,
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <KeyboardAvoidingWrapper enabled={false}>
+      <Input label="Disabled avoidance" placeholder="Keyboard will cover on native" />
+    </KeyboardAvoidingWrapper>
+  ),
+};

package/src/layouts/KeyboardAvoidingWrapper/behavior.ts

@@ -0,0 +1,13 @@
+export type KeyboardAvoidingBehavior = "padding" | "height" | "position";
+
+/**
+ * Native KeyboardAvoidingView default: padding on iOS, height on Android.
+ * An explicit `behavior` prop always wins.
+ */
+export function resolveKeyboardAvoidingBehavior(
+  platform: string,
+  behavior?: KeyboardAvoidingBehavior,
+): KeyboardAvoidingBehavior {
+  if (behavior) return behavior;
+  return platform === "ios" ? "padding" : "height";
+}

package/src/layouts/KeyboardAvoidingWrapper/index.native.tsx

@@ -1,6 +1,9 @@
 import type { PropsWithChildren } from "react";
 import { KeyboardAvoidingView, Platform, StyleSheet } from "react-native";
 import { YStack, type YStackProps } from "tamagui";
+import { resolveKeyboardAvoidingBehavior, type KeyboardAvoidingBehavior } from "./behavior";
+
+export type { KeyboardAvoidingBehavior } from "./behavior";
 
 export interface KeyboardAvoidingWrapperProps extends YStackProps {
   /**
@@ -9,7 +12,7 @@ export interface KeyboardAvoidingWrapperProps extends YStackProps {
    * - 'height': Reduce height to avoid keyboard (default for Android)
    * - 'position': Change position to avoid keyboard
    */
-  behavior?: "padding" | "height" | "position";
+  behavior?: KeyboardAvoidingBehavior;
   /**
    * Additional offset to add when keyboard is visible
    */
@@ -22,11 +25,9 @@ export interface KeyboardAvoidingWrapperProps extends YStackProps {
 }
 
 /**
- * KeyboardAvoidingWrapper - Native implementation
+ * KeyboardAvoidingWrapper — native KeyboardAvoidingView.
  *
- * Wraps content in a KeyboardAvoidingView that automatically adjusts
- * its layout when the keyboard appears. Uses platform-specific
- * default behavior (padding for iOS, height for Android).
+ * No owned surface — only platform keyboard offset. Consumer `{...stackProps}` last.
  */
 export function KeyboardAvoidingWrapper({
   children,
@@ -35,9 +36,7 @@ export function KeyboardAvoidingWrapper({
   enabled = true,
   ...stackProps
 }: PropsWithChildren<KeyboardAvoidingWrapperProps>) {
-  // Default behavior based on platform
-  const defaultBehavior = Platform.OS === "ios" ? "padding" : "height";
-  const effectiveBehavior = behavior || defaultBehavior;
+  const effectiveBehavior = resolveKeyboardAvoidingBehavior(Platform.OS, behavior);
 
   return (
     <KeyboardAvoidingView
@@ -46,7 +45,13 @@ export function KeyboardAvoidingWrapper({
       keyboardVerticalOffset={keyboardVerticalOffset}
       enabled={enabled}
     >
-      <YStack flex={1} {...stackProps}>
+      <YStack
+        data-testid="keyboard-avoiding-wrapper"
+        data-keyboard-avoiding="native"
+        data-enabled={String(enabled)}
+        flex={1}
+        {...stackProps}
+      >
         {children}
       </YStack>
     </KeyboardAvoidingView>