Add a Generic Box Styled Component for Third-Party Components

[divineniiquaye]

Description

Uniwind currently provides the withUniwind HOC to enable styling for third-party components, which works well. However, it introduces some friction when used repeatedly across an app, especially when dealing with many external components.

I’d like to propose adding a generic styled component (e.g. Box) that can style any component, including third-party ones, while preserving proper type inference.

Current Approach

Today, styling third-party components requires explicitly wrapping each component with withUniwind:
https://gist.github.com/divineniiquaye/3d7fe856842d121e2375d0c93d56b4d5

import { withUniwind } from 'uniwind'
import { SafeAreaView } from 'react-native-safe-area-context'

const StyledSafeAreaView = withUniwind(SafeAreaView)

<StyledSafeAreaView className="flex-1 bg-background">
  {/* content */}
</StyledSafeAreaView>

This works, but it:

• Adds boilerplate
• Requires creating new wrapped components
• Doesn’t scale ergonomically when many third-party components are involved

Proposed API

Introduce a generic styled component such as Box that internally uses withUniwind and can render any component via an as prop:

import { Box } from 'uniwind'
import { SafeAreaView } from 'react-native-safe-area-context';

<Box
  as={SafeAreaView}
  className="flex-1 bg-background"
>
  {/* content */}
</Box>

Key Expectations

• Box should accept any React component (including third-party ones)
• Props should be properly inferred based on the as component
• className support should work identically to native Uniwind components
• Internally, Box can leverage withUniwind to avoid duplication

Thanks for the great work on Uniwind — this feature would make third-party integration even smoother 🚀

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Feature Request: Support Webpack and/or Vite #148
• Support updating theme CSS variables from JS for React Native #184
• How to use LinearGradient with withUniwind for colors array #150

👤 Suggested Assignees

• dlebedynskyi
• bmsteven
• denniske

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[divineniiquaye]

@coderabbitai plan

[coderabbitai]

Coding Plan

Approach

Add a generic Box component that can render any React component via an as prop while maintaining full type inference and className support, reducing boilerplate when styling third-party components.

Observations

Uniwind is a Tailwind CSS bindings library for React Native with a dual-platform architecture. Components are organized into platform-specific implementations (native and web) in packages/uniwind/src/components/, exported via the uniwind/components path. The library uses the withUniwind HOC to enable className-based styling on components, with auto-mapping and manual mapping modes. The type system leverages mapped types to convert className props to style props. Components follow a pattern of wrapping React Native components and using utilities like copyComponentProperties rather than forwardRef for component composition.

Assumptions

Assumption 1: Default Component Behavior

Options Considered:

• Default to React Native's View component (most generic container)
• Require as prop to be explicitly provided

Chosen Option: Default to View component

Rationale: This provides the most ergonomic developer experience and aligns with common patterns in styling libraries where the base component is a generic container. View is semantically neutral and works for most use cases.

Assumption 2: withUniwind Integration Strategy

Options Considered:

• Use withUniwind with auto-mapping mode (automatic className prop detection)
• Use withUniwind with manual mapping mode (explicit className to style mapping)
• Implement custom styling logic without withUniwind

Chosen Option: Use withUniwind with auto-mapping mode

Rationale: This is the simplest approach that aligns with the ticket's explicit requirement to "leverage withUniwind" internally. Auto-mapping will automatically detect and handle className props on whatever component is passed via as, providing the most flexible and maintainable solution.

Assumption 3: Ref Forwarding Pattern

Options Considered:

• Introduce React.forwardRef for proper ref typing (standard for polymorphic components)
• Follow existing codebase pattern using copyComponentProperties utility
• Skip ref forwarding entirely

Chosen Option: Follow existing codebase patterns without forwardRef initially

Rationale: The codebase consistently uses copyComponentProperties and spreads props without forwardRef. Introducing forwardRef only for Box would create an inconsistency. If ref support becomes necessary based on user feedback, it can be added in a follow-up without breaking changes.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Type System Foundation

Define TypeScript types to support polymorphic component behavior with proper prop inference based on the as prop.

Task 1: Create Polymorphic Type Utilities

Define core type utilities for handling the polymorphic as prop pattern with proper type inference.

• Create new file packages/uniwind/src/components/types.ts for shared component type utilities
• Define PolymorphicComponentProps<T, P> generic type that merges custom props P with intrinsic props from component type T
• Define constraint type that extends React.ElementType to restrict valid component types
• Handle prop conflict resolution between custom props and component-specific props (e.g., ensure className is preserved)
• Export these utilities for reuse by other potential polymorphic components

Task 2: Define Box Component Types

Create type definitions specific to the Box component using the polymorphic utilities.

• Define BoxOwnProps interface containing Box-specific props (className and any future Box-only features)
• Define BoxProps<T> generic type using PolymorphicComponentProps that includes as?: T prop with proper default
• Define BoxComponent type representing the component interface with proper generic signature
• Ensure the default type parameter for the generic is typeof View for React Native
• Add proper JSDoc comments explaining the polymorphic behavior and as prop usage

🤖 Prompt for AI agents

Build the TypeScript type foundation for polymorphic component behavior with the
`as` prop pattern.

Create `packages/uniwind/src/components/types.ts`:
- Define `PolymorphicComponentProps<T, P>` generic type that merges custom props
P with intrinsic props from component type T
- Add constraint type extending `React.ElementType` for valid component types
- Handle prop conflict resolution to preserve className
- Export utilities for reuse

Define Box-specific types:
- Create `BoxOwnProps` interface with className and future Box props
- Define `BoxProps<T>` generic using PolymorphicComponentProps with `as?: T`
prop
- Define `BoxComponent` type with proper generic signature
- Set default type parameter to `typeof View`
- Add JSDoc comments explaining polymorphic behavior

Phase 2: Component Implementation

Create platform-specific Box implementations that use withUniwind internally to provide className styling capabilities.

Task 1: Implement Native Box Component

Create the React Native Box component implementation that integrates with withUniwind.

• Create packages/uniwind/src/components/native/Box.tsx
• Import View from React Native as the default render target
• Import withUniwind HOC from ../../hoc/withUniwind
• Implement Box as a functional component that destructures as prop with View as default
• Use withUniwind with auto-mapping mode to wrap the target component (the value of as prop or View)
• Spread remaining props to the wrapped component
• Apply BoxComponent type signature to ensure proper generic typing

Task 2: Implement Web Box Component

Create the web platform Box component with equivalent API to native implementation.

• Create packages/uniwind/src/components/web/Box.tsx
• Import View from react-native (RN Web compatibility)
• Follow the same component structure as native Box for API consistency
• Use withUniwind HOC from ../../hoc/withUniwind (web version will be automatically selected)
• Ensure className conversion works properly with web's toRNWClassName() through withUniwind
• Match the type signature of the native Box implementation

Task 3: Add Box Tests

Create test files to verify Box behavior and type safety.

• Create test file in packages/uniwind/src/components/__tests__/Box.test.tsx (or appropriate test location)
• Test Box renders with default View component when no as prop provided
• Test Box properly forwards className prop and applies styles
• Test Box renders custom component passed via as prop
• Test Box properly forwards all props to the underlying component
• Add type-level tests if existing test infrastructure supports it (verify prop inference)

🤖 Prompt for AI agents

Implement platform-specific Box components using withUniwind for className
styling.

Create native Box at `packages/uniwind/src/components/native/Box.tsx`:
- Import View from React Native and withUniwind HOC
- Implement functional component destructuring `as` prop with View default
- Wrap target component with withUniwind in auto-mapping mode
- Spread remaining props to wrapped component
- Apply BoxComponent type signature

Create web Box at `packages/uniwind/src/components/web/Box.tsx`:
- Import View from react-native for RN Web compatibility
- Match native Box structure for API consistency
- Use withUniwind HOC (web version auto-selected)
- Ensure className conversion through withUniwind

Add tests at `packages/uniwind/src/components/__tests__/Box.test.tsx`:
- Verify default View rendering without `as` prop
- Test className forwarding and style application
- Test custom component rendering via `as` prop
- Verify all props forwarded correctly
- Add type-level tests for prop inference if supported

Phase 3: Export & Public API Integration

Integrate Box into the public API following established export patterns.

Task 1: Add Component Exports

Export Box from the components module following the existing lazy-loading pattern.

• Add Box entry to packages/uniwind/src/components/index.ts using the CommonJS getter pattern (Object.defineProperty approach)
• Add Box to packages/uniwind/src/components/web/index.ts for web-specific exports
• Ensure the export uses the same lazy-loading mechanism as other components for consistency
• Verify conditional exports in package.json properly route to correct platform implementations

Task 2: Export Type Definitions

Make Box types available for developers using TypeScript.

• Add Box types to main type exports in packages/uniwind/src/components/index.ts type definitions
• Export BoxProps, BoxComponent, and any related polymorphic type utilities from packages/uniwind/src/components/types.ts
• Consider if PolymorphicComponentProps should be publicly exported for developers creating custom polymorphic components
• Update any existing type barrel exports to include the new Box types

Task 3: Update Documentation Examples

Add usage examples demonstrating Box component capabilities.

• Add Box usage example to apps/expo-router/app/sections/ (or appropriate example location)
• Show example of Box with third-party component via as prop (e.g., SafeAreaView from react-native-safe-area-context)
• Demonstrate Box with default View behavior (no as prop)
• Show comparison between withUniwind HOC approach and Box approach to highlight ergonomic benefits
• Include example of proper TypeScript prop inference with different component types

🤖 Prompt for AI agents

Integrate Box into the public API following existing patterns and add
documentation.

Add component exports:
- Add Box to `packages/uniwind/src/components/index.ts` using CommonJS getter
pattern (Object.defineProperty)
- Add Box to `packages/uniwind/src/components/web/index.ts` for web exports
- Use lazy-loading mechanism consistent with other components
- Verify package.json conditional exports route correctly

Export type definitions:
- Add Box types to main type exports in
`packages/uniwind/src/components/index.ts`
- Export BoxProps, BoxComponent, and polymorphic utilities from
`packages/uniwind/src/components/types.ts`
- Consider public export of PolymorphicComponentProps for custom components
- Update type barrel exports

Add documentation examples at `apps/expo-router/app/sections/`:
- Show Box with third-party component via `as` prop (e.g., SafeAreaView)
- Demonstrate default View behavior without `as` prop
- Compare withUniwind HOC vs Box approach for ergonomic benefits
- Include TypeScript prop inference examples with different component types

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Build the TypeScript type foundation for polymorphic component behavior with the
`as` prop pattern.

Create `packages/uniwind/src/components/types.ts`:
- Define `PolymorphicComponentProps<T, P>` generic type that merges custom props
P with intrinsic props from component type T
- Add constraint type extending `React.ElementType` for valid component types
- Handle prop conflict resolution to preserve className
- Export utilities for reuse

Define Box-specific types:
- Create `BoxOwnProps` interface with className and future Box props
- Define `BoxProps<T>` generic using PolymorphicComponentProps with `as?: T`
prop
- Define `BoxComponent` type with proper generic signature
- Set default type parameter to `typeof View`
- Add JSDoc comments explaining polymorphic behavior
===============================================================================

Task: 2

Implement platform-specific Box components using withUniwind for className
styling.

Create native Box at `packages/uniwind/src/components/native/Box.tsx`:
- Import View from React Native and withUniwind HOC
- Implement functional component destructuring `as` prop with View default
- Wrap target component with withUniwind in auto-mapping mode
- Spread remaining props to wrapped component
- Apply BoxComponent type signature

Create web Box at `packages/uniwind/src/components/web/Box.tsx`:
- Import View from react-native for RN Web compatibility
- Match native Box structure for API consistency
- Use withUniwind HOC (web version auto-selected)
- Ensure className conversion through withUniwind

Add tests at `packages/uniwind/src/components/__tests__/Box.test.tsx`:
- Verify default View rendering without `as` prop
- Test className forwarding and style application
- Test custom component rendering via `as` prop
- Verify all props forwarded correctly
- Add type-level tests for prop inference if supported
===============================================================================

Task: 3

Integrate Box into the public API following existing patterns and add
documentation.

Add component exports:
- Add Box to `packages/uniwind/src/components/index.ts` using CommonJS getter
pattern (Object.defineProperty)
- Add Box to `packages/uniwind/src/components/web/index.ts` for web exports
- Use lazy-loading mechanism consistent with other components
- Verify package.json conditional exports route correctly

Export type definitions:
- Add Box types to main type exports in
`packages/uniwind/src/components/index.ts`
- Export BoxProps, BoxComponent, and polymorphic utilities from
`packages/uniwind/src/components/types.ts`
- Consider public export of PolymorphicComponentProps for custom components
- Update type barrel exports

Add documentation examples at `apps/expo-router/app/sections/`:
- Show Box with third-party component via `as` prop (e.g., SafeAreaView)
- Demonstrate default View behavior without `as` prop
- Compare withUniwind HOC vs Box approach for ergonomic benefits
- Include TypeScript prop inference examples with different component types

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!