react-native-twc 1.1.3 → 1.2.0

package/README.md

@@ -12,6 +12,8 @@ A lightweight library for creating styled React Native components using Tailwind
 - 🦄 **Works with any React Native component**
 - 🚀 **First-class `tailwind-merge` and `cva` support**
 - 📱 **Built for React Native + NativeWind**
+- 🎁 **`withChildren`** — Pre-define children rendering with type safety
+- 🔀 **Smart style merging** — `attrs` styles merge with props styles
 
 ## Installation
 
@@ -209,6 +211,73 @@ const Box = twc(View).transientProps(["size"])<Props>((props) => ({
 <Box size="lg" />
 ```
 
+### Using `withChildren`
+
+Pre-define how children should be rendered. Useful for creating button components with consistent text styling:
+
+```tsx
+import { Pressable, Text } from "react-native";
+import { twx } from "react-native-twc";
+
+// Default: accepts any ReactNode
+const Card = twx(View).withChildren((children) => (
+  <View className="p-4">{children}</View>
+))`bg-white rounded-lg`;
+
+// With generic type: accepts only string
+const Button = twx(Pressable).withChildren<string>((text) => (
+  <Text className="text-white font-bold text-center">{text}</Text>
+))`bg-blue-500 py-3 px-6 rounded-lg`;
+
+// Usage
+<Button>Submit</Button>  // text is typed as string
+<Card><CustomComponent /></Card>  // children is ReactNode
+```
+
+Combine with `attrs` for powerful component composition:
+
+```tsx
+const FloatButton = twx(Pressable)
+  .attrs({
+    activeOpacity: 0.8,
+    style: { shadowColor: "#000", shadowOffset: { width: 0, height: 2 } },
+  })
+  .withChildren<string>((text) => (
+    <Text className="text-white text-lg">{text}</Text>
+  ))`absolute bottom-4 right-4 bg-purple-500 rounded-full p-4`;
+
+<FloatButton>Add</FloatButton>
+```
+
+### Smart Style Merging with `attrs`
+
+When using `attrs` with a `style` prop, styles are intelligently merged (not replaced) when you pass additional styles:
+
+```tsx
+const Card = twc(View).attrs({
+  style: { backgroundColor: "white", padding: 16, borderRadius: 8 },
+})`shadow-lg`;
+
+// Styles are merged: padding and borderRadius are preserved
+<Card style={{ backgroundColor: "blue", margin: 10 }}>
+  Content
+</Card>
+// Result: { backgroundColor: "blue", padding: 16, borderRadius: 8, margin: 10 }
+```
+
+This also works with dynamic attrs:
+
+```tsx
+type Props = TwcComponentProps<typeof View> & { $padded?: boolean };
+
+const Box = twc(View).attrs<Props>((props) => ({
+  style: { padding: props.$padded ? 20 : 0 },
+}))`bg-gray-100`;
+
+<Box $padded style={{ margin: 10 }}>Content</Box>
+// Result: { padding: 20, margin: 10 }
+```
+
 ## API Reference
 
 ### `twc(Component)`
@@ -258,12 +327,47 @@ import { twx } from "react-native-twc";
 const Title = twx(Text)`font-bold`;
 ```
 
+### `.withChildren<T>(renderer)`
+
+Pre-define children rendering with optional type constraint.
+
+```tsx
+// Accept any ReactNode (default)
+const Card = twc(View).withChildren((children) => (
+  <Wrapper>{children}</Wrapper>
+))`bg-white`;
+
+// Accept only string
+const Button = twc(Pressable).withChildren<string>((text) => (
+  <Text className="text-white">{text}</Text>
+))`bg-blue-500`;
+
+// Accept string or undefined
+const Label = twc(View).withChildren<string | undefined>((text) => (
+  <Text>{text ?? "Default"}</Text>
+))`p-2`;
+```
+
+### `.attrs(attributes)` - Style Merging
+
+When `attrs` includes a `style` prop, it will be merged with any `style` passed to the component (not replaced):
+
+```tsx
+const Box = twc(View).attrs({
+  style: { padding: 10 },  // Base style
+})`bg-white`;
+
+<Box style={{ margin: 5 }} />  // Merged: { padding: 10, margin: 5 }
+```
+
 ## Differences from TWC (Web)
 
 | Feature | TWC (Web) | react-native-twc |
 |---------|-----------|------------------|
 | HTML tags (`twc.div`) | ✅ Supported | ❌ Not supported |
 | `asChild` prop | ✅ Supported | ❌ Not supported |
+| `withChildren` | ❌ Not supported | ✅ Supported |
+| Smart style merging | ❌ Not supported | ✅ Supported |
 | React Native components | ❌ Not optimized | ✅ Fully supported |
 | NativeWind | ❌ Not designed for | ✅ First-class support |
 

package/dist/index.d.ts

@@ -25,9 +25,31 @@ type ResultProps<TComponent extends RNComponentType, TProps, TExtraProps, TCompo
  * 支持模板字符串语法和函数形式
  */
 type Template<TComponent extends RNComponentType, TCompose extends AbstractCompose, TExtraProps, TParentProps = undefined> = <TProps = TParentProps>(strings: TemplateStringsArray | ((props: ResultProps<TComponent, TProps, TExtraProps, TCompose>) => 'className' extends keyof TProps ? TProps['className'] : Parameters<TCompose>[0]), ...values: any[]) => React.ForwardRefExoticComponent<ResultProps<TComponent, TProps, TExtraProps, TCompose>>;
+/**
+ * Children 渲染器类型
+ * 用于包裹 children 并返回 ReactNode
+ * TChildren 默认为 React.ReactNode，但可以指定为更具体的类型如 string
+ */
+type ChildrenRenderer<TChildren = React.ReactNode> = (children: TChildren) => React.ReactNode;
+/**
+ * 带 withChildren 的模板类型
+ * 用于 attrs 返回后仍可调用 withChildren
+ */
+type TemplateWithChildren<TComponent extends RNComponentType, TCompose extends AbstractCompose, TExtraProps, TParentProps = undefined> = Template<TComponent, TCompose, TExtraProps, TParentProps> & {
+    /**
+     * 预定义 children 的渲染方式
+     * 可通过泛型指定 children 类型，默认为 React.ReactNode
+     * @example
+     * // 默认接受任意 ReactNode
+     * const Card = twc(View).withChildren((children) => <Wrapper>{children}</Wrapper>)`...`
+     * // 指定只接受 string
+     * const Button = twc(Pressable).withChildren<string>((text) => <Text>{text}</Text>)`...`
+     */
+    withChildren: <TChildren = React.ReactNode>(renderer: ChildrenRenderer<TChildren>) => Template<TComponent, TCompose, TExtraProps, TParentProps>;
+};
 /**
  * 第一级模板类型
- * 包含 attrs 和 transientProps 方法
+ * 包含 attrs、transientProps 和 withChildren 方法
  */
 type FirstLevelTemplate<TComponent extends RNComponentType, TCompose extends AbstractCompose, TExtraProps> = Template<TComponent, TCompose, TExtraProps> & {
     /**
@@ -35,7 +57,7 @@ type FirstLevelTemplate<TComponent extends RNComponentType, TCompose extends Abs
      * @example
      * const TextInput = twc(RNTextInput).attrs({ keyboardType: 'email-address' })`...`
      */
-    attrs: <TProps = undefined>(attrs: (Omit<Partial<ComponentProps<TComponent>>, 'className'> & Record<string, any>) | ((props: ResultProps<TComponent, TProps, TExtraProps, TCompose>) => Record<string, any>)) => Template<TComponent, TCompose, TExtraProps, TProps>;
+    attrs: <TProps = undefined>(attrs: (Omit<Partial<ComponentProps<TComponent>>, 'className'> & Record<string, any>) | ((props: ResultProps<TComponent, TProps, TExtraProps, TCompose>) => Record<string, any>)) => TemplateWithChildren<TComponent, TCompose, TExtraProps, TProps>;
 } & {
     /**
      * 防止特定 props 被转发到底层组件
@@ -43,6 +65,17 @@ type FirstLevelTemplate<TComponent extends RNComponentType, TCompose extends Abs
      * const Title = twc(Text).transientProps(['$size'])`...`
      */
     transientProps: (fn: string[] | ((prop: string) => boolean)) => FirstLevelTemplate<TComponent, TCompose, TExtraProps>;
+} & {
+    /**
+     * 预定义 children 的渲染方式
+     * 可通过泛型指定 children 类型，默认为 React.ReactNode
+     * @example
+     * // 默认接受任意 ReactNode
+     * const Card = twc(View).withChildren((children) => <Wrapper>{children}</Wrapper>)`...`
+     * // 指定只接受 string
+     * const Button = twc(Pressable).withChildren<string>((text) => <Text>{text}</Text>)`...`
+     */
+    withChildren: <TChildren = React.ReactNode>(renderer: ChildrenRenderer<TChildren>) => FirstLevelTemplate<TComponent, TCompose, TExtraProps>;
 };
 /**
  * TWC 主类型

package/dist/index.js

@@ -13,11 +13,38 @@ function filterProps(props, shouldForwardProp) {
 	return filteredProps;
 }
 
+function flattenStyle(style) {
+	if (style == null) return {};
+	if (Array.isArray(style)) return style.reduce((acc, s) => ({
+		...acc,
+		...flattenStyle(s)
+	}), {});
+	return style;
+}
+
+function mergeStyles(baseStyle, overrideStyle) {
+	if (baseStyle == null) return overrideStyle;
+	if (overrideStyle == null) return baseStyle;
+	return {
+		...flattenStyle(baseStyle),
+		...flattenStyle(overrideStyle)
+	};
+}
+
+function mergePropsWithAttrs(attrs, props) {
+	const merged = {
+		...attrs,
+		...props
+	};
+	if (attrs.style != null && props.style != null) merged.style = mergeStyles(attrs.style, props.style);
+	return merged;
+}
+
 const createTwc = (config = {}) => {
 	const compose = config.compose || clsx;
 	const defaultShouldForwardProp = config.shouldForwardProp || ((prop) => prop[0] !== "$");
 	const wrap = (Component) => {
-		const createTemplate = (attrs, shouldForwardProp = defaultShouldForwardProp) => {
+		const createTemplate = (attrs, shouldForwardProp = defaultShouldForwardProp, childrenRenderer) => {
 			const componentCache = /* @__PURE__ */ new Map();
 			const template = (stringsOrFn, ...values) => {
 				const isClassFn = typeof stringsOrFn === "function";
@@ -28,22 +55,19 @@ const createTwc = (config = {}) => {
 				const isAttrsFunction = typeof attrs === "function";
 				const staticAttrs = !isAttrsFunction && hasAttrs ? attrs : void 0;
 				const ForwardedComponent = React.forwardRef((p, ref) => {
-					const { className: classNameProp, ...rest } = p;
+					const { className: classNameProp, children, ...rest } = p;
 					let finalProps;
 					if (!hasAttrs) finalProps = filterProps(rest, shouldForwardProp);
-					else if (isAttrsFunction) finalProps = filterProps({
-						...attrs(p),
-						...rest
-					}, shouldForwardProp);
-					else finalProps = filterProps({
-						...staticAttrs,
-						...rest
-					}, shouldForwardProp);
+					else if (isAttrsFunction) finalProps = filterProps(mergePropsWithAttrs(attrs(p), rest), shouldForwardProp);
+					else finalProps = filterProps(mergePropsWithAttrs(staticAttrs, rest), shouldForwardProp);
 					const baseClassName = isClassFn ? stringsOrFn(p) : tplClassName;
+					const finalClassName = typeof baseClassName === "function" ? (renderProps) => compose(baseClassName(renderProps), typeof classNameProp === "function" ? classNameProp(renderProps) : classNameProp) : compose(baseClassName, classNameProp);
+					const finalChildren = childrenRenderer ? childrenRenderer(children) : children;
 					return /* @__PURE__ */ jsx(Component, {
 						ref,
-						className: typeof baseClassName === "function" ? (renderProps) => compose(baseClassName(renderProps), typeof classNameProp === "function" ? classNameProp(renderProps) : classNameProp) : compose(baseClassName, classNameProp),
-						...finalProps
+						className: finalClassName,
+						...finalProps,
+						children: finalChildren
 					});
 				});
 				ForwardedComponent.displayName = `twc(${Component.displayName || Component.name || "Component"})`;
@@ -51,10 +75,13 @@ const createTwc = (config = {}) => {
 				return ForwardedComponent;
 			};
 			template.transientProps = (fnOrArray) => {
-				return createTemplate(attrs, typeof fnOrArray === "function" ? (prop) => !fnOrArray(prop) : (prop) => !fnOrArray.includes(prop));
+				return createTemplate(attrs, typeof fnOrArray === "function" ? (prop) => !fnOrArray(prop) : (prop) => !fnOrArray.includes(prop), childrenRenderer);
+			};
+			template.withChildren = (renderer) => {
+				return createTemplate(attrs, shouldForwardProp, renderer);
 			};
-			if (attrs === void 0) template.attrs = (attrs$1) => {
-				return createTemplate(attrs$1, shouldForwardProp);
+			if (attrs === void 0) template.attrs = (newAttrs) => {
+				return createTemplate(newAttrs, shouldForwardProp, childrenRenderer);
 			};
 			return template;
 		};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-twc",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Create reusable React Native + NativeWind components with Tailwind CSS syntax.",
   "type": "module",
   "main": "./dist/index.js",