@kbach/react 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,253 @@
+# @kbach/react
+
+Tailwind-like utility classes for **React (web)**. Same class names as Tailwind, zero stylesheet required — classes are converted to inline styles at render time via a custom JSX runtime.
+
+```tsx
+/** @jsxImportSource @kbach/react */
+
+<div className="bg-white dark:bg-gray-10 p-4 rounded-xl shadow" />
+<div className="bg-blue-7 hover:bg-blue-8 dark:bg-indigo-6 rounded-lg px-6 py-3" />
+<div className="bg-[#6366f1] p-[14px] rounded-[20px]" />
+```
+
+## Install
+
+```bash
+npm install @kbach/react
+```
+
+## Setup
+
+### 1. Configure the JSX runtime
+
+**tsconfig.json** (applies to every file in the project)
+
+```jsonc
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@kbach/react"
+  }
+}
+```
+
+**Vite**
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react({ jsxImportSource: '@kbach/react' })],
+});
+```
+
+**Babel**
+
+```js
+// babel.config.js
+module.exports = {
+  presets: [
+    ['@babel/preset-react', { runtime: 'automatic', importSource: '@kbach/react' }],
+  ],
+};
+```
+
+**Per-file pragma** (no config change required)
+
+```tsx
+/** @jsxImportSource @kbach/react */
+```
+
+### 2. Wrap your app
+
+```tsx
+import { ThemeProvider } from '@kbach/react';
+
+export default function Root() {
+  return (
+    <ThemeProvider defaultMode="system">
+      <App />
+    </ThemeProvider>
+  );
+}
+```
+
+## API
+
+### `className` prop
+
+Works on any HTML element or React component once the JSX runtime is configured.
+
+```tsx
+<div className="bg-white dark:bg-gray-10 p-4 rounded-xl" />
+<p className="text-gray-10 dark:text-white text-lg font-bold" />
+<button className="bg-blue-7 hover:bg-blue-8 pressed:bg-blue-8 rounded-lg px-4 py-2" />
+```
+
+### `styled(Component, classes)`
+
+Pre-style any component. Returns a new component that merges the base classes with any `className` or `tw` prop passed at use time.
+
+```tsx
+import { styled } from '@kbach/react';
+
+const Card = styled('div', 'bg-white dark:bg-gray-9 rounded-2xl p-6 shadow');
+const Title = styled('h2', 'text-2xl font-bold text-gray-10 dark:text-white');
+const Button = styled(
+  'button',
+  'bg-blue-7 hover:bg-blue-8 dark:bg-indigo-6 rounded-xl px-6 py-3'
+);
+
+// Pass extra classes at use time
+<Card tw="mt-4 mb-2">
+  <Title tw="text-3xl">Hello</Title>
+</Card>
+```
+
+### `useStyles(classes)`
+
+Resolve classes to a style object inside a component.
+
+```tsx
+import { useStyles } from '@kbach/react';
+
+function Badge() {
+  const style = useStyles('bg-blue-6 dark:bg-indigo-6 px-3 py-1 rounded-full');
+  return <span style={style}>New</span>;
+}
+```
+
+### `tw(classes)`
+
+Resolve classes outside a component (static contexts).
+
+```tsx
+import { tw } from '@kbach/react';
+
+const cardStyle = tw('bg-white p-4 rounded-xl') as React.CSSProperties;
+```
+
+### `cx(...classes)`
+
+Conditionally join class strings. Falsy values are ignored.
+
+```tsx
+import { cx } from '@kbach/react';
+
+<div className={cx(
+  'p-4 rounded-xl',
+  isSelected && 'border-2 border-blue-6',
+  isDisabled && 'opacity-50',
+)} />
+```
+
+### `useTheme()`
+
+```tsx
+import { useTheme } from '@kbach/react';
+
+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.
+
+```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 |
+| `hover:` | Mouse hover |
+| `pressed:` | Click / touch |
+| `focus:` | Element focused |
+| `active:` | Element active |
+| `disabled:` | Element disabled |
+
+```tsx
+<div className="dark:hover:bg-gray-9" />
+<button className="dark:pressed:bg-indigo-8" />
+```
+
+## Arbitrary values
+
+```tsx
+<div className="bg-[#6366f1]" />
+<div className="p-[14px]" />
+<div className="text-[18px]" />
+<div className="bg-[rgba(99,102,241,0.15)]" />
+```
+
+## Color with opacity
+
+```tsx
+<div className="bg-blue-6/50" />   {/* 50% opacity */}
+<div 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`
+
+## 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: '72px' },
+    },
+  },
+
+  plugins: [
+    ({ addUtility, theme }) => {
+      addUtility('border-brand', {
+        borderColor: theme('colors.brand.6'),
+        borderWidth: 2,
+      });
+    },
+  ],
+};
+```
+
+```tsx
+import { updateConfig } from '@kbach/react';
+
+updateConfig({ extend: { theme: { colors: { brand: { 6: '#6366f1' } } } } });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/react",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "React / React Native components and hooks for the Kbach framework",
   "source": "./src/index.ts",
   "main": "./dist/index.js",