@kbach/native 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,302 @@
+# @kbach/native
+
+Tailwind-like utility classes for **React Native and Expo**. One package includes everything: the core engine, JSX runtime, Babel plugin for compile-time optimization, and Metro config helper.
+
+```tsx
+import { View, Text, TouchableOpacity } from 'react-native';
+import { styled } from '@kbach/native';
+
+const Button = styled(
+  TouchableOpacity,
+  'bg-blue-7 pressed:bg-blue-8 dark:bg-indigo-6 rounded-xl px-6 py-3 items-center'
+);
+
+export default function Screen() {
+  return (
+    <View className="flex-1 bg-gray-2 dark:bg-gray-11 p-4">
+      <Text className="text-2xl font-bold text-gray-10 dark:text-white mb-4">
+        Hello Kbach
+      </Text>
+      <Button>
+        <Text className="text-white font-semibold">Press me</Text>
+      </Button>
+    </View>
+  );
+}
+```
+
+## Install
+
+```bash
+npm install @kbach/native
+```
+
+That's it. Core engine, Babel plugin, and Metro helpers are bundled — nothing else to install.
+
+## Setup
+
+### 1. babel.config.js
+
+```js
+const { createKbachConfig } = require('@kbach/native');
+module.exports = createKbachConfig();
+```
+
+If you need to keep an existing Babel config:
+
+```js
+const { withKbachBabel } = require('@kbach/native');
+
+module.exports = withKbachBabel({
+  presets: ['babel-preset-expo'],
+  plugins: [/* your existing plugins */],
+});
+```
+
+### 2. metro.config.js
+
+```js
+const { getDefaultConfig } = require('expo/metro-config');
+const { withKbach } = require('@kbach/native');
+
+const config = getDefaultConfig(__dirname);
+module.exports = withKbach(config);
+```
+
+### 3. Wrap your app
+
+```tsx
+import { ThemeProvider } from '@kbach/native';
+
+export default function App() {
+  return (
+    <ThemeProvider defaultMode="system">
+      <AppContent />
+    </ThemeProvider>
+  );
+}
+```
+
+After changing `babel.config.js` or `metro.config.js`, clear the Metro cache:
+
+```bash
+npx expo start --clear
+```
+
+## API
+
+### `className` prop
+
+Works on any React Native component — `View`, `Text`, `TouchableOpacity`, `TextInput`, and third-party components.
+
+```tsx
+<View className="flex-1 bg-gray-2 dark:bg-gray-11 p-4" />
+<Text className="text-lg font-bold text-gray-10 dark:text-white" />
+<TouchableOpacity className="bg-blue-7 pressed:bg-blue-8 rounded-xl px-6 py-3" />
+```
+
+### `styled(Component, classes)`
+
+Pre-style any component. Handles interaction states (`pressed:`, `focus:`, etc.) automatically.
+
+```tsx
+import { styled } from '@kbach/native';
+import { View, Text, TouchableOpacity, TextInput } from 'react-native';
+
+const Card = styled(View, 'bg-white dark:bg-gray-9 rounded-2xl p-6 shadow');
+const Title = styled(Text, 'text-2xl font-bold text-gray-10 dark:text-white');
+const Button = styled(
+  TouchableOpacity,
+  'bg-blue-7 pressed:bg-blue-8 dark:bg-indigo-6 dark:pressed:bg-indigo-7 rounded-xl px-6 py-3'
+);
+const Input = styled(
+  TextInput,
+  'border border-gray-4 dark:border-gray-7 focus:border-blue-6 bg-white dark:bg-gray-8 rounded-lg px-4 py-3'
+);
+```
+
+Pass extra classes at use time with the `tw` prop:
+
+```tsx
+<Card tw="mt-4 mb-2">
+  <Title tw="text-3xl">Hello</Title>
+</Card>
+```
+
+### `useStyles(classes)`
+
+Resolve classes to a style object inside a component. Use this when you need a value for the `style` prop.
+
+```tsx
+import { useStyles } from '@kbach/native';
+import { View, Text } from 'react-native';
+
+function Badge() {
+  const containerStyle = useStyles('bg-blue-6 dark:bg-indigo-6 px-3 py-1 rounded-full');
+  const textStyle = useStyles('text-white text-xs font-bold');
+
+  return (
+    <View style={containerStyle}>
+      <Text style={textStyle}>New</Text>
+    </View>
+  );
+}
+```
+
+### `tw(classes)`
+
+Resolve classes outside a component, for use in `StyleSheet.create()` or static contexts.
+
+```tsx
+import { StyleSheet } from 'react-native';
+import { tw } from '@kbach/native';
+
+const styles = StyleSheet.create({
+  container: tw('flex-1 bg-white p-4') as object,
+  title: tw('text-2xl font-bold text-gray-10') as object,
+});
+```
+
+### `cx(...classes)`
+
+Conditionally join class strings. Falsy values are ignored.
+
+```tsx
+import { cx } from '@kbach/native';
+
+<View className={cx(
+  'p-4 rounded-xl',
+  isSelected && 'border-2 border-blue-6',
+  isDisabled && 'opacity-50',
+)} />
+```
+
+### `useTheme()`
+
+```tsx
+import { useTheme } from '@kbach/native';
+
+const { mode, resolvedMode, isDark, setMode, toggle } = useTheme();
+```
+
+| Value | Type | Description |
+|---|---|---|
+| `mode` | `'light' \| 'dark' \| 'system'` | User-selected mode |
+| `resolvedMode` | `'light' \| 'dark'` | Resolved after system lookup |
+| `isDark` | `boolean` | Shorthand for `resolvedMode === 'dark'` |
+| `setMode(mode)` | `fn` | Set mode explicitly |
+| `toggle()` | `fn` | Toggle between light and dark |
+
+### `ThemeToggle`
+
+Drop-in toggle component that works on both web and native.
+
+```tsx
+<ThemeToggle />                                 // button (default)
+<ThemeToggle variant="switch" />               // toggle switch
+<ThemeToggle variant="icon-button" />          // icon button
+<ThemeToggle variant="button" includeSystem /> // three-way selector
+```
+
+## Modifiers
+
+Up to **3 modifiers** can be chained in any order.
+
+| Modifier | Trigger |
+|---|---|
+| `dark:` | Dark mode active |
+| `light:` | Light mode active |
+| `pressed:` | Touch pressed |
+| `focus:` | Element focused |
+| `active:` | Element active |
+| `disabled:` | Element disabled |
+
+```tsx
+<View className="dark:bg-gray-10" />
+<TouchableOpacity className="dark:pressed:bg-indigo-8" />
+```
+
+## Arbitrary values
+
+```tsx
+<View className="bg-[#6366f1]" />
+<View className="p-[14px]" />
+<Text className="text-[18px]" />
+<View className="rounded-[20px]" />
+<View className="bg-[rgba(99,102,241,0.15)]" />
+```
+
+## Negative values
+
+```tsx
+<View className="-mt-4" />   {/* marginTop: -16 */}
+<View className="-mx-2" />   {/* marginHorizontal: -8 */}
+```
+
+## Color with opacity
+
+```tsx
+<View className="bg-blue-6/50" />   {/* 50% opacity */}
+<View className="bg-gray-10/75" />  {/* 75% opacity */}
+```
+
+## Color scale
+
+Colors use an 11-shade scale where **1 is lightest** and **11 is darkest**.
+
+```
+bg-gray-1   (near white)  →  bg-gray-6  (mid)  →  bg-gray-11  (near black)
+```
+
+Available families: `slate` `gray` `zinc` `neutral` `stone` `red` `orange` `amber` `yellow` `lime` `green` `emerald` `teal` `cyan` `sky` `blue` `indigo` `violet` `purple` `fuchsia` `pink` `rose`
+
+## Common utilities
+
+| Category | Examples |
+|---|---|
+| **Background** | `bg-white`, `bg-gray-10`, `bg-blue-6`, `bg-[#fff]` |
+| **Text** | `text-sm`, `text-lg`, `text-2xl`, `text-gray-10`, `font-bold` |
+| **Padding** | `p-4`, `px-6`, `py-3`, `pt-2`, `pb-4` |
+| **Margin** | `m-4`, `mx-auto`, `mt-2`, `mb-4`, `-mt-4` |
+| **Size** | `w-full`, `h-12`, `w-[200px]` |
+| **Flex** | `flex-1`, `flex-row`, `items-center`, `justify-between`, `gap-4` |
+| **Border** | `border`, `border-2`, `border-gray-4`, `rounded-xl`, `rounded-full` |
+| **Shadow** | `shadow`, `shadow-md`, `shadow-lg` |
+| **Opacity** | `opacity-50`, `opacity-75` |
+
+## Configuration
+
+```js
+// kbach.config.js
+module.exports = {
+  darkMode: 'attribute', // 'attribute' | 'class' | 'media'
+
+  theme: {
+    colors: {
+      brand: { 1: '#eff6ff', 6: '#3b82f6', 10: '#1e3a5f' },
+    },
+  },
+
+  extend: {
+    theme: {
+      colors: { brand: { 6: '#6366f1' } },
+      spacing: { 18: 72 },
+    },
+  },
+
+  plugins: [
+    ({ addUtility, theme }) => {
+      addUtility('border-brand', {
+        borderColor: theme('colors.brand.6'),
+        borderWidth: 2,
+      });
+    },
+  ],
+};
+```
+
+```tsx
+import { updateConfig } from '@kbach/native';
+
+updateConfig({ extend: { theme: { colors: { brand: { 6: '#6366f1' } } } } });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/native",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Single-package Kbach install for React Native and Expo — includes core, components, Babel plugin, and Metro config",
   "source": "./src/index.ts",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@kbach/core": "0.1.0",
-    "@kbach/react": "0.1.0",
+    "@kbach/react": "0.1.1",
     "babel-plugin-kbach": "0.1.0"
   },
   "devDependencies": {