docs: add documentation for new hooks

Austin1serb · Austin1serb · commit e835625b853b · 2025-08-05T10:29:26.000-07:00
diff --git a/README.md b/README.md
@@ -20,10 +20,10 @@ Pre‑render your UI once, flip a `data-*` attribute to update — that's it.
 
 ## 🚀 Live Demo
 
-| Example                                 | Link                                                                                                                                           | What it shows                                                 | Link to Code                                                                                                                                 |
-| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| Interactive menu with render tracker    | <a href="https://zero-ui.dev/" target="_blank" rel="noopener noreferrer"><strong>Main Demo↗</strong></a>                                      | Compare Zero‑UI vs. React side‑by‑side while toggling a menu. | <a href="https://github.com/react-zero-ui/core/tree/main/examples/demo" target="_blank" rel="noopener noreferrer">Github</a>                 |
-| React benchmark (10 000 nested nodes)   | <a href="https://zero-ui.dev/react" target="_blank" rel="noopener noreferrer"><strong>React 10k↗</strong></a>                                 | How long the traditional React render path takes.             | <a href="https://github.com/react-zero-ui/core/tree/main/examples/demo/src/app/react" target="_blank" rel="noopener noreferrer">Github</a>   |
+| Example | Link | What it shows | Link to Code |
+| --- | --- | --- | --- |
+| Interactive menu with render tracker | <a href="https://zero-ui.dev/" target="_blank" rel="noopener noreferrer"><strong>Main Demo↗</strong></a> | Compare Zero‑UI vs. React side‑by‑side while toggling a menu. | <a href="https://github.com/react-zero-ui/core/tree/main/examples/demo" target="_blank" rel="noopener noreferrer">Github</a> |
+| React benchmark (10 000 nested nodes)   | <a href="https://zero-ui.dev/react" target="_blank" rel="noopener noreferrer"><strong>React 10k↗</strong></a> | How long the traditional React render path takes.             | <a href="https://github.com/react-zero-ui/core/tree/main/examples/demo/src/app/react" target="_blank" rel="noopener noreferrer">Github</a>   |
 | Zero‑UI benchmark (10 000 nested nodes) | <a href="https://zero-ui.dev/zero-ui" target="_blank" rel="noopener noreferrer"><strong style="text-align: nowrap;">Zero‑UI 10k↗</strong></a> | Identical DOM, but powered by Zero‑UI's `data-*` switch.      | <a href="https://github.com/react-zero-ui/core/tree/main/examples/demo/src/app/zero-ui" target="_blank" rel="noopener noreferrer">Github</a> |
 
 ---
diff --git a/README2.md b/README2.md
@@ -0,0 +1,146 @@
+
+## ⚡️ React Zero-UI 
+*The ZERO re-render UI state library*
+
+**The fastest possible UI updates in React. Period.**
+Zero runtime, zero React re-renders, and the simplest developer experience ever.
+
+See the proof in [here](/docs/demo)
+
+<a href="https://bundlephobia.com/package/@react-zero-ui/core@0.2.6" target="_blank" rel="noopener noreferrer"><img src="https://badgen.net/bundlephobia/minzip/@react-zero-ui/core@0.2.6" alt="npm version" /> </a><a href="https://www.npmjs.com/package/@austinserb/react-zero-ui" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/npm/v/@react-zero-ui/core" alt="npm version" /></a> <a href="https://opensource.org/licenses/MIT" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a> ![CI](https://github.com/react-zero-ui/core/actions/workflows/ci.yml/badge.svg?branch=main)
+
+---
+
+
+## 🔥 Core Concept: *"Pre-Rendering"*
+
+Why re-render UI if all states are known at build time? React Zero-UI **pre-renders** UI states once, and flips `data-*` attribute to update - that's it.
+
+**Example:**
+
+```tsx
+const [, setTheme] = useUI("theme", "dark");
+
+// Flip theme to "light"
+setTheme("light"); // data-theme="light" on body
+```
+
+Tailwind usage:
+
+```html
+<div class="theme-dark:bg-black theme-light:bg-white">Fast & Reactive</div>
+```
+
+---
+
+## 🚀 How it Works (Build-Time Magic)
+
+React Zero-UI uses a hyper-optimized AST resolver in development/build-time that scans your codebase for:
+
+* `useUI` and `useScopedUI` hook usage.
+* Any variables resolving to strings (e.g., `'theme'`, `'modal-open'`).
+* Tailwind variant classes (e.g., `theme-dark:bg-black`).
+
+This generates:
+
+* Optimal CSS with scoped variant selectors.
+* Initial data-attributes injected onto the body (zero FOUC).
+* **Zero runtime overhead in production**.
+
+---
+
+## ⚙️ Installation (Zero-UI CLI)
+
+pre-requisites:
+- Tailwind CSS v4 must already be initialized in your project.
+- Vite or Next.js (App Router)
+
+
+```bash
+npx create-zero-ui
+```
+> for manual configuration, see [manual installation.](https://github.com/react-zero-ui/core)
+
+---
+
+## 🔨 API: `useUI` Hook (Global UI state)
+
+Simple hook mirroring React's `useState`:
+
+```tsx
+import { useUI } from '@react-zero-ui/core';
+
+const [theme, setTheme] = useUI("theme", "dark");
+```
+
+* Flips global `data-theme` attribute on `<body>`.
+* Zero React re-renders.
+* Initial state pre-rendered at build time (no FOUC).
+
+---
+
+## 🎯 API: `useScopedUI` Hook (Scoped UI state)
+
+Control UI states at the element-level:
+
+```tsx
+import { useScopedUI } from '@react-zero-ui/core';
+
+const [theme, setTheme] = useScopedUI("theme", "dark");
+
+// Flips data-theme attribute on the specific ref element
+<div ref={setTheme.ref} data-theme={theme}>
+  Scoped UI Here
+</div>
+```
+
+* Data attribute flips on specific target element.
+* Generates scoped CSS selectors only applying within the target element.
+
+---
+
+## 🌈 API: CSS Variables Support
+
+Sometimes CSS variables are more efficient. React Zero-UI makes it trivial using the `CssVar` option:
+
+```tsx
+import { useUI, CssVar } from '@react-zero-ui/core';
+
+const [blur, setBlur] = useUI("blur", "0px", CssVar);
+
+// Flips CSS variable --blur on body
+setBlur("5px"); // body { --blur: 5px }
+```
+
+**Scoped CSS Variable Example:**
+
+```tsx
+const [blur, setBlur] = useScopedUI("blur", "0px", CssVar);
+
+<div ref={setBlur.ref} style={{ "--blur": blur }}>
+  Scoped blur effect.
+</div>
+```
+
+---
+
+## 🧪 Experimental: SSR-safe `zeroOnClick`
+
+Enable client-side interactivity **without leaving server components**.
+Just 300 bytes of runtime overhead.
+
+See [experimental](./docs/assets/experimental.md) for more details.
+
+## 📦 Summary of Benefits
+
+* **Zero React re-renders:** Pure CSS-driven UI state.
+* **Pre-rendered UI:** All states injected at build-time. and only loaded when needed.
+* **Tiny footprint:** <350 bytes runtime, zero overhead for CSS states.
+* **SSR-safe interaction:** Static server components, fully interactive.
+* **Amazing DX:** Simple hooks, auto-generated Tailwind variants.
+* **Highly optimized AST resolver:** Fast, cached build process.
+
+React Zero-UI delivers the fastest, simplest, most performant way to handle global and scoped UI state in modern React applications.
+
+
+Made with ❤️  for the React community by [@austinserb](https://github.com/austin1serb)
diff --git a/docs/assets/demo.md b/docs/assets/demo.md
@@ -0,0 +1,35 @@
+## 🚀 Demo + Benchmarks
+
+| Example | Link | What it shows | Link to Code |
+| -- | -- | -- | -- |
+| Interactive menu with render tracker    |  [Main Demo](https://zero-ui.dev/)   | Compare Zero‑UI vs. React side‑by‑side while toggling a menu. | [Github](https://zero-ui.dev/react)   |
+| React benchmark (10 000 nested nodes)   | [React 10k](https://zero-ui.dev/react)   | How long the traditional React render path takes.   | [Github](https://github.com/react-zero-ui/core/tree/main/examples/demo/src/app/react)   |
+| Zero‑UI benchmark (10 000 nested nodes) | [Zero‑UI 10k](https://zero-ui.dev/zero-ui) | Identical DOM, but powered by Zero‑UI's `data-*` switch.   | [Github](https://github.com/react-zero-ui/core/tree/main/examples/demo/src/app/zero-ui) |
+
+source code for the demo: [Zero Rerender Demo](/examples/demo/)
+
+---
+
+## 🧐 Why Zero‑UI?
+
+Every `setState` in React triggers the full VDOM → Diff → Reconciliation → Paint pipeline. For _pure UI state_ (themes, menus, toggles) that work is wasted.
+
+**Zero‑UI introduces "_PRE‑rendering_":**
+
+1. Tailwind variants for every state are **generated at build‑time**.
+2. The app **pre‑renders once**.
+3. Runtime state changes only **flip a `data-*`**.
+
+Result → **5-10× faster visual updates** with **ZERO additional bundle cost**.
+
+### 📊 Micro‑benchmarks (Apple M1)
+
+| Nodes updated | React state | Zero‑UI | Speed‑up |
+| ------------- | ----------- | ------- | -------- |
+| 10,000        | \~50 ms     | \~5 ms  | **10×**  |
+| 25,000        | \~180 ms    | \~15 ms | **12×**  |
+| 50,000        | \~300 ms    | \~20 ms | **15×**  |
+
+Re‑run these numbers yourself via the links above with chrome dev tools.
+
+---
diff --git a/docs/assets/experimental.md b/docs/assets/experimental.md
@@ -0,0 +1,58 @@
+
+## 🧪 Experimental: SSR-safe `zeroOnClick`
+
+Enable client-side interactivity **without leaving server components**.
+Just 300 bytes of runtime overhead.
+
+### ⚙️ Installation (Zero-UI Experimental)
+
+```bash
+npm install @react-zero-ui/core@0.3.1-beta.2
+```
+
+Initialize once in your root:
+
+```tsx
+"use client"
+
+/* ① import the generated defaults */
+import { variantKeyMap } from "../.zero-ui/attributes"
+/* ② activate the runtime shipped in the package */
+import { activateZeroUiRuntime } from "@react-zero-ui/core/experimental/runtime"
+
+activateZeroUiRuntime(variantKeyMap)
+
+export const ZeroUiRuntime = () => null // this component just runs the side effect
+
+```
+
+### Usage
+
+```tsx
+import { zeroSSR } from "@react-zero-ui/core/experimental"
+
+<div {...zeroSSR.onClick("theme", ["dark", "light", "spanish"])} >
+  Click me to cycle themes!
+</div>
+```
+
+Usage is the same as the `useUI` hooks:
+```html
+<div class="theme-dark:bg-black theme-light:bg-white">
+  Interactive Server Component!
+</div>
+```
+
+**Scoped Version:**
+
+```tsx
+import { zeroScopedOnClick } from '@react-zero-ui/experimental';
+
+<div data-model="open"> // set the scope with a data-attribute that matches the key
+  <button {...scopedZeroSSR.onClick("modal", ["open", "closed"])}>
+    Toggle Modal
+  </button>
+</div>
+```
+
+see the source code for the `zeroSSR` object, see [experimental](/packages/core/src/experimental)
diff --git a/docs/assets/manual-installation-vite.md b/docs/assets/manual-installation-vite.md
@@ -0,0 +1,53 @@
+
+### Manual Install Vite
+
+```bash
+npm install @react-zero-ui/core @tailwindcss/postcss
+```
+
+---
+
+## 🔧 Setup
+
+### Vite
+
+```js
+// vite.config.*
+import zeroUI from "@react-zero-ui/core/vite";
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+ 
+export default defineConfig({
+   // ❗️Remove the default `tailwindcss()` plugin — Zero‑UI extends it internally
+  plugins: [zeroUI(), react()]
+});
+```
+### Next.js (App Router)
+
+2. **Add the PostCSS plugin (must come _before_ Tailwind).**
+
+   ```js
+   // postcss.config.js
+   module.exports = { plugins: { '@react-zero-ui/core/postcss': {}, tailwindcss: {} } };
+   ```
+
+---
+
+
+
+
+1. **Spread `bodyAttributes` on `<body>`** in your root layout.
+
+   ```tsx
+   // app/layout.tsx
+   import { bodyAttributes } from './.zero-ui/attributes';
+   // or:  import { bodyAttributes } from '../.zero-ui/attributes';
+
+   export default function RootLayout({ children }) {
+   	return (
+   		<html lang="en">
+   			<body {...bodyAttributes}>{children}</body>
+   		</html>
+   	);
+   }
+   ```
diff --git a/packages/core/src/experimental/README.md b/packages/core/src/experimental/README.md
@@ -0,0 +1,70 @@
+# 🧪 Experimental Runtime (Zero-UI)
+
+This folder contains the **SSR-safe runtime logic** for handling interactivity in React server components without using `use client`. It is designed to be tiny (\~300 bytes), deterministic, and fully compatible with React Zero-UI's pre-rendered data-attribute model.
+
+---
+
+## 📦 What This Code Does
+
+### `activateZeroUiRuntime()`
+
+This is the core runtime entrypoint. When called:
+
+1. **Registers a single global click event listener** on `document`.
+
+2. **Listens for clicks** on any element (or ancestor) with a `data-ui` attribute.
+
+3. **Parses the `data-ui` directive** with this format:
+
+   * `data-ui="global:key(val1,val2,...)"` → flips `data-key` on `document.body`
+   * `data-ui="scoped:key(val1,val2,...)"` → flips `data-key` on closest matching ancestor or self
+
+4. **Cycles the value** of the matching `data-*` attribute in a round-robin fashion.
+
+5. **Updates the DOM instantly**, enabling Tailwind to respond via selectors (e.g. `theme-dark:bg-black`).
+
+It guards against duplicate initialization using a `window.__zero` flag.
+
+---
+
+### `zeroSSR.onClick()` / `scopedZeroSSR.onClick()`
+
+These utility functions generate valid `data-ui` attributes for use in JSX/TSX.
+
+They return a prop like this:
+
+```tsx
+{ 'data-ui': 'global:theme(dark,light)' }
+```
+
+or
+
+```tsx
+{ 'data-ui': 'scoped:modal(open,closed)' }
+```
+
+**In development**, they also perform validation:
+
+* Ensures the key is kebab-case.
+* Ensures at least one value is provided.
+
+---
+
+## 🧠 Design Notes
+
+* **No React state or re-renders** involved.
+* Works entirely via DOM `data-*` mutations.
+* Compatible with all server components.
+* Fully tree-shakable and side-effect-free unless `activateZeroUiRuntime()` is called.
+
+This design makes it ideal for pairing with Tailwind-style conditional classes in static components.
+
+---
+
+## 🧼 Summary
+
+* `activateZeroUiRuntime()` → enables click handling on static components via `data-ui`
+* `zeroSSR` / `scopedZeroSSR` → emit valid click handlers as JSX props
+* No state. No runtime overhead. Works in server components.
+
+This runtime is the bridge between **static HTML** and **interactive UX**, while keeping everything **server-rendered** and blazing fast.
