react-native-twc 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-Present Greg Bergé
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+# react-native-twc
+
+> Create reusable React Native + NativeWind components with Tailwind CSS syntax
+
+This project is a **React Native adaptation** of [TWC (react-twc)](https://github.com/gregberge/twc) by [Greg Bergé](https://github.com/gregberge). The original TWC library provides an elegant way to create styled React components with Tailwind CSS. This fork adapts the library specifically for React Native with NativeWind support.
+
+## Features
+
+- ⚡️ **Lightweight** — only ~1KB minified
+- ✨ **Full TypeScript support** with autocompletion
+- 🎨 **Dynamic styling** based on props
+- 🦄 **Works with any React Native component**
+- 🚀 **First-class `tailwind-merge` and `cva` support**
+- 📱 **Built for React Native + NativeWind**
+
+## Installation
+
+```bash
+# npm
+npm install react-native-twc
+
+# yarn
+yarn add react-native-twc
+
+# bun
+bun add react-native-twc
+```
+
+### Peer Dependencies
+
+Make sure you have the following peer dependencies installed:
+
+```bash
+npm install react react-native nativewind tailwind-merge
+```
+
+## Usage
+
+### Basic Usage
+
+**Without `twc`:**
+
+```tsx
+import * as React from "react";
+import { View, Text, ViewProps } from "react-native";
+import clsx from "clsx";
+
+const Card = React.forwardRef<View, ViewProps>(({ className, ...props }, ref) => (
+  <View
+    ref={ref}
+    className={clsx("rounded-lg border bg-slate-100 p-4 shadow-sm", className)}
+    {...props}
+  />
+));
+```
+
+**With `twc`:**
+
+```tsx
+import { View } from "react-native";
+import { twc } from "react-native-twc";
+
+const Card = twc(View)`rounded-lg border bg-slate-100 p-4 shadow-sm`;
+```
+
+### Creating Styled Components
+
+```tsx
+import { View, Text, Pressable, TextInput } from "react-native";
+import { twc } from "react-native-twc";
+
+// Basic styled components
+const Container = twc(View)`flex-1 bg-white p-4`;
+const Title = twc(Text)`text-2xl font-bold text-gray-900`;
+const Subtitle = twc(Text)`text-lg text-gray-600`;
+
+// Styled input
+const Input = twc(TextInput)`border border-gray-300 rounded-lg px-4 py-2`;
+
+// Styled button
+const Button = twc(Pressable)`bg-blue-500 py-3 px-6 rounded-lg`;
+const ButtonText = twc(Text)`text-white font-semibold text-center`;
+```
+
+### Dynamic Styling with Props
+
+Use the `$` prefix for transient props that won't be passed to the underlying component:
+
+```tsx
+import { Pressable, Text } from "react-native";
+import { twc, TwcComponentProps } from "react-native-twc";
+
+type ButtonProps = TwcComponentProps<typeof Pressable> & {
+  $variant?: "primary" | "secondary" | "danger";
+};
+
+const Button = twc(Pressable)<ButtonProps>((props) => [
+  "py-3 px-6 rounded-lg font-semibold",
+  {
+    "bg-blue-500": props.$variant === "primary",
+    "bg-gray-200": props.$variant === "secondary",
+    "bg-red-500": props.$variant === "danger",
+  },
+]);
+
+// Usage
+<Button $variant="primary">
+  <Text className="text-white">Click me</Text>
+</Button>
+```
+
+### Using with `attrs`
+
+Add default props to your components:
+
+```tsx
+import { TextInput } from "react-native";
+import { twc } from "react-native-twc";
+
+const EmailInput = twc(TextInput).attrs({
+  keyboardType: "email-address",
+  autoCapitalize: "none",
+  placeholder: "Enter your email",
+})`border border-gray-300 rounded-lg px-4 py-2`;
+
+// Usage
+<EmailInput onChangeText={(text) => console.log(text)} />
+```
+
+### Using with CVA (Class Variance Authority)
+
+```tsx
+import { Pressable } from "react-native";
+import { cva, VariantProps } from "class-variance-authority";
+import { twc, TwcComponentProps } from "react-native-twc";
+
+const buttonVariants = cva("rounded-lg font-semibold", {
+  variants: {
+    $intent: {
+      primary: "bg-blue-500 text-white",
+      secondary: "bg-gray-200 text-gray-800",
+      danger: "bg-red-500 text-white",
+    },
+    $size: {
+      sm: "py-1 px-2 text-sm",
+      md: "py-2 px-4 text-base",
+      lg: "py-3 px-6 text-lg",
+    },
+  },
+  defaultVariants: {
+    $intent: "primary",
+    $size: "md",
+  },
+});
+
+type ButtonProps = TwcComponentProps<typeof Pressable> &
+  VariantProps<typeof buttonVariants>;
+
+const Button = twc(Pressable)<ButtonProps>(({ $intent, $size }) =>
+  buttonVariants({ $intent, $size })
+);
+
+// Usage
+<Button $intent="danger" $size="lg">
+  <Text>Delete</Text>
+</Button>
+```
+
+### Using with Tailwind Merge
+
+Use the built-in `twx` for automatic class conflict resolution:
+
+```tsx
+import { Text } from "react-native";
+import { twx } from "react-native-twc";
+
+const Title = twx(Text)`font-bold text-lg`;
+
+// Later classes override earlier ones
+<Title className="font-normal text-sm">Hello</Title>
+// Result: "font-normal text-sm" (conflicts resolved)
+```
+
+Or create your own instance:
+
+```tsx
+import { twMerge } from "tailwind-merge";
+import { createTwc } from "react-native-twc";
+
+const twc = createTwc({ compose: twMerge });
+```
+
+### Custom Transient Props
+
+By default, props starting with `$` are not forwarded. Customize this behavior:
+
+```tsx
+import { View } from "react-native";
+import { twc, TwcComponentProps } from "react-native-twc";
+
+type Props = TwcComponentProps<typeof View> & { size: "sm" | "lg" };
+
+const Box = twc(View).transientProps(["size"])<Props>((props) => ({
+  "w-4 h-4": props.size === "sm",
+  "w-8 h-8": props.size === "lg",
+}));
+
+// 'size' won't be passed to the underlying View
+<Box size="lg" />
+```
+
+## API Reference
+
+### `twc(Component)`
+
+Wraps a React Native component and returns a template function.
+
+```tsx
+const StyledView = twc(View)`bg-white p-4`;
+```
+
+### `createTwc(config)`
+
+Creates a custom TWC instance with configuration options.
+
+```tsx
+const twc = createTwc({
+  compose: twMerge, // Custom class merging function
+  shouldForwardProp: (prop) => !prop.startsWith("_"), // Custom prop filtering
+});
+```
+
+### `TwcComponentProps<T>`
+
+Utility type to extract props from a TWC-wrapped component.
+
+```tsx
+type CardProps = TwcComponentProps<typeof View>;
+```
+
+### `cn(...inputs)`
+
+Utility function combining `clsx` and `tailwind-merge`.
+
+```tsx
+import { cn } from "react-native-twc";
+
+const className = cn("p-4", condition && "bg-blue-500", ["rounded", "shadow"]);
+```
+
+### `twx`
+
+Pre-configured TWC instance using `tailwind-merge` for class conflict resolution.
+
+```tsx
+import { twx } from "react-native-twc";
+
+const Title = twx(Text)`font-bold`;
+```
+
+## Differences from Original TWC
+
+| Feature | Original TWC | react-native-twc |
+|---------|--------------|------------------|
+| HTML tags (`twc.div`) | ✅ Supported | ❌ Not supported |
+| `asChild` prop | ✅ Supported | ❌ Not supported |
+| React Native components | ❌ Not optimized | ✅ Fully supported |
+| NativeWind | ❌ Not designed for | ✅ First-class support |
+
+## Acknowledgements
+
+- [TWC (react-twc)](https://github.com/gregberge/twc) by [Greg Bergé](https://github.com/gregberge) - The original inspiration and foundation for this project
+- [NativeWind](https://www.nativewind.dev/) - Tailwind CSS for React Native
+- [styled-components](https://styled-components.com) - Where the template literal API originated
+- [tailwind-merge](https://github.com/dcastil/tailwind-merge) - Intelligent Tailwind class merging
+
+## License
+
+MIT License © 2023-Present [Greg Bergé](https://github.com/gregberge)
+
+---
+
+**Note:** This is a community fork adapted for React Native. For the original React (web) version, please visit [react-twc](https://github.com/gregberge/twc).

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+import { type ClassValue, clsx } from 'clsx';
+import React from 'react';
+export { clsx as cx };
+type AbstractCompose = (...params: any) => any;
+/**
+ * React Native 组件类型定义
+ * 支持任何接受 className 或 style prop 的 React Native 组件
+ */
+type RNComponentType = React.ComponentType<any>;
+/**
+ * 获取组件的 Props 类型
+ */
+type ComponentProps<T> = T extends React.ComponentType<infer P> ? P : never;
+/**
+ * 结果 Props 类型
+ * 根据泛型参数组合最终的 props 类型
+ */
+type ResultProps<TComponent extends RNComponentType, TProps, TExtraProps, TCompose extends AbstractCompose> = TProps extends undefined ? TExtraProps extends undefined ? Omit<ComponentProps<TComponent>, 'className'> & {
+    className?: Parameters<TCompose>[0];
+} : Omit<ComponentProps<TComponent>, 'className'> & {
+    className?: Parameters<TCompose>[0];
+} & TExtraProps : TProps;
+/**
+ * 模板函数类型
+ * 支持模板字符串语法和函数形式
+ */
+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>>;
+/**
+ * 第一级模板类型
+ * 包含 attrs 和 transientProps 方法
+ */
+type FirstLevelTemplate<TComponent extends RNComponentType, TCompose extends AbstractCompose, TExtraProps> = Template<TComponent, TCompose, TExtraProps> & {
+    /**
+     * 为组件添加额外的默认 props
+     * @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>;
+} & {
+    /**
+     * 防止特定 props 被转发到底层组件
+     * @example
+     * const Title = twc(Text).transientProps(['$size'])`...`
+     */
+    transientProps: (fn: string[] | ((prop: string) => boolean)) => FirstLevelTemplate<TComponent, TCompose, TExtraProps>;
+};
+/**
+ * TWC 主类型
+ * 只支持传入 React Native 组件，不支持字符串标签
+ */
+type Twc<TCompose extends AbstractCompose> = <T extends RNComponentType>(component: T) => FirstLevelTemplate<T, TCompose, undefined>;
+/**
+ * TWC 组件 Props 工具类型
+ * 用于获取 TWC 组件的 props 类型
+ */
+export type TwcComponentProps<TComponent extends RNComponentType, TCompose extends AbstractCompose = typeof clsx> = ResultProps<TComponent, undefined, undefined, TCompose>;
+/**
+ * 配置类型
+ */
+export type Config<TCompose extends AbstractCompose> = {
+    /**
+     * className 合并函数，默认使用 clsx
+     * 可以替换为 tailwind-merge 等库
+     */
+    compose?: TCompose;
+    /**
+     * 判断 prop 是否应该转发到底层组件的函数
+     * 默认规则: prop => prop[0] !== "$" (以 $ 开头的不转发)
+     */
+    shouldForwardProp?: (prop: string) => boolean;
+};
+/**
+ * 创建 TWC 实例的工厂函数
+ *
+ * @param config - 配置选项
+ * @returns TWC 实例
+ *
+ * @example
+ * // 基础使用
+ * import { View, Text } from 'react-native';
+ * const twc = createTwc();
+ * const Card = twc(View)`bg-white rounded-lg p-4`;
+ * const Title = twc(Text)`text-xl font-bold`;
+ *
+ * @example
+ * // 使用 tailwind-merge
+ * import { twMerge } from 'tailwind-merge';
+ * const twc = createTwc({ compose: twMerge });
+ */
+export declare const createTwc: <TCompose extends AbstractCompose = typeof clsx>(config?: Config<TCompose>) => Twc<TCompose>;
+/**
+ * 默认的 TWC 实例
+ * 使用 clsx 作为 compose 函数
+ */
+export declare const twc: Twc<typeof clsx>;
+export declare const cn: (...inputs: ClassValue[]) => string;
+/**
+ * 带tailwind-merge的 TWC 实例
+ * 使用 cn 作为 compose 函数
+ */
+export declare const twx: Twc<(...inputs: ClassValue[]) => string>;

package/dist/index.js

@@ -0,0 +1,65 @@
+// src/index.tsx
+import { clsx } from "clsx";
+import React from "react";
+import { twMerge } from "tailwind-merge";
+import { jsxDEV } from "react/jsx-dev-runtime";
+function filterProps(props, shouldForwardProp) {
+  const filteredProps = {};
+  const keys = Object.keys(props);
+  for (let i = 0;i < keys.length; i++) {
+    const prop = keys[i];
+    if (shouldForwardProp(prop)) {
+      filteredProps[prop] = props[prop];
+    }
+  }
+  return filteredProps;
+}
+var createTwc = (config = {}) => {
+  const compose = config.compose || clsx;
+  const defaultShouldForwardProp = config.shouldForwardProp || ((prop) => prop[0] !== "$");
+  const wrap = (Component) => {
+    const createTemplate = (attrs, shouldForwardProp = defaultShouldForwardProp) => {
+      const template = (stringsOrFn, ...values) => {
+        const isClassFn = typeof stringsOrFn === "function";
+        const tplClassName = !isClassFn && String.raw({ raw: stringsOrFn }, ...values);
+        const ForwardedComponent = React.forwardRef((p, ref) => {
+          const { className: classNameProp, ...rest } = p;
+          const resolvedAttrs = typeof attrs === "function" ? attrs(p) : attrs ? attrs : {};
+          const filteredProps = filterProps({ ...resolvedAttrs, ...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 Comp = Component;
+          return /* @__PURE__ */ jsxDEV(Comp, {
+            ref,
+            className: finalClassName,
+            ...filteredProps
+          }, undefined, false, undefined, this);
+        });
+        ForwardedComponent.displayName = `twc(${Component.displayName || Component.name || "Component"})`;
+        return ForwardedComponent;
+      };
+      template.transientProps = (fnOrArray) => {
+        const shouldForwardProp2 = typeof fnOrArray === "function" ? (prop) => !fnOrArray(prop) : (prop) => !fnOrArray.includes(prop);
+        return createTemplate(attrs, shouldForwardProp2);
+      };
+      if (attrs === undefined) {
+        template.attrs = (attrs2) => {
+          return createTemplate(attrs2, shouldForwardProp);
+        };
+      }
+      return template;
+    };
+    return createTemplate();
+  };
+  return wrap;
+};
+var twc = createTwc();
+var cn = (...inputs) => twMerge(clsx(inputs));
+var twx = createTwc({ compose: cn });
+export {
+  twx,
+  twc,
+  clsx as cx,
+  createTwc,
+  cn
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+    "name": "react-native-twc",
+    "version": "1.0.0",
+    "description": "Create reusable React Native + NativeWind components with Tailwind CSS syntax.",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "types": "./dist/index.d.ts",
+    "scripts": {
+        "test": "bun test",
+        "build": "rm -rf dist && bun run build:js && bun run build:dts",
+        "build:js": "bun build src/index.tsx --outdir dist --format esm --external react --external react-native --external clsx --external tailwind-merge",
+        "build:dts": "tsc -p tsconfig.build.json",
+        "check-types": "tsc --noEmit",
+        "publish": "bun run build && npm publish --access public"
+    },
+    "keywords": [
+        "react-native",
+        "nativewind",
+        "tailwind",
+        "css",
+        "components",
+        "styled",
+        "styled-components",
+        "expo"
+    ],
+    "author": "Greg Bergé",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gregberge/twc.git"
+    },
+    "homepage": "https://react-twc.vercel.app",
+    "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/gregberge"
+    },
+    "devDependencies": {
+        "@eslint/eslintrc": "^3.3.1",
+        "@eslint/js": "^9.30.0",
+        "@happy-dom/global-registrator": "^18.0.1",
+        "@testing-library/react": "^16.3.0",
+        "@types/bun": "^1.2.5",
+        "@types/react": "^19.1.8",
+        "@typescript-eslint/eslint-plugin": "^8.35.0",
+        "@typescript-eslint/parser": "^8.35.0",
+        "class-variance-authority": "^0.7.1",
+        "eslint": "^9.30.0",
+        "happy-dom": "^18.0.1",
+        "prettier": "^3.6.2",
+        "react": "^19.1.0",
+        "react-dom": "^19.1.0",
+        "tailwind-merge": "^3.3.1",
+        "typescript": "^5.8.3",
+        "typescript-eslint": "^8.35.0",
+        "ultracite": "7.0.10"
+    },
+    "dependencies": {
+        "clsx": "^2.1.1"
+    },
+    "peerDependencies": {
+        "react": ">=18.0.0",
+        "react-native": ">=0.72.0",
+        "nativewind": ">=4.0.0",
+        "tailwind-merge": ">=3.3.1"
+    },
+    "peerDependenciesMeta": {
+        "react-native": {
+            "optional": true
+        },
+        "nativewind": {
+            "optional": true
+        }
+    }
+}