@kbach/react 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,270 @@
+# @kbach/react
+
+Tailwind-like utility classes for **React (web)**. Classes are converted to inline styles at render time through a custom JSX runtime — no stylesheet required.
+
+```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**
+
+```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 | function | Set mode explicitly |
+| toggle | function | 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 or 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 — 1 is lightest, 11 is darkest.
+
+```
+shade 1  ·  2  ·  3  ·  4  ·  5  ·  6  ·  7  ·  8  ·  9  ·  10  ·  11
+light ─────────────────────────────────────────────────────────── dark
+```
+
+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-2xl`, `text-gray-10`, `font-bold` |
+| Padding | `p-4`, `px-6`, `py-3` |
+| Margin | `m-4`, `mx-auto`, `mt-2`, `-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` |
+| 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: '72px' },
+    },
+  },
+
+  plugins: [
+    ({ addUtility, theme }) => {
+      addUtility('border-brand', {
+        borderColor: theme('colors.brand.6'),
+        borderWidth: 2,
+      });
+    },
+  ],
+};
+```
+
+Apply at runtime:
+
+```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.2",
   "description": "React / React Native components and hooks for the Kbach framework",
   "source": "./src/index.ts",
   "main": "./dist/index.js",