create-nuclo 0.1.1

package/templates/basic/node_modules/nuclo/README.md

@@ -0,0 +1,727 @@
+# nuclo
+
+**A lightweight, imperative DOM framework with explicit updates.**
+
+Build interactive UIs with plain functions, mutable JavaScript objects, and explicit `update()` calls. Nuclo is imperative: nothing re-renders until you call `update()`. No virtual DOM, no proxies, and no hidden state tracking.
+
+```ts
+import 'nuclo';
+
+let count = 0;
+
+const counter = div(
+  h1(() => `Count: ${count}`),
+  button('Increment', on('click', () => {
+    count++;
+    update();
+  }))
+);
+
+render(counter, document.body);
+```
+
+## Why nuclo?
+
+- **Explicit and Predictable** – You control when updates happen with a simple `update()` call
+- **Direct DOM Manipulation** – Work directly with the DOM, no virtual layer in between
+- **Tiny Footprint** – ~10 KB gzipped, zero dependencies
+- **Global Tag Builders** – Natural API with global functions for all HTML and SVG elements
+- **TypeScript-First** – Full type definitions for all 175 HTML and SVG builders
+- **Targeted DOM Updates** – `update()` re-runs dynamic bindings and only touches DOM where values changed
+- **Atomic Styling** – Built-in `css()` / `createCss()` with TypeScript autocomplete, theming, and SSR CSS collection
+- **Server-Side Rendering** – `renderToString()` + `hydrate()` with a lightweight DOM polyfill
+
+---
+
+## Installation
+
+```bash
+npm install nuclo
+```
+
+### Usage
+
+Simply import once to register all global functions:
+
+```ts
+import 'nuclo';
+
+// Now use div(), update(), on(), list(), when(), render(), etc. globally
+let count = 0;
+const app = div(
+  h1(() => `Count: ${count}`),
+  button('Click', on('click', () => { count++; update(); }))
+);
+render(app, document.body);
+```
+
+### TypeScript Setup
+
+Add to your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["nuclo/types"]
+  }
+}
+```
+
+Or in your `vite-env.d.ts`:
+
+```ts
+/// <reference types="nuclo/types" />
+```
+
+---
+
+## Quick Examples
+
+### Counter
+
+```ts
+import 'nuclo';
+
+let count = 0;
+
+const app = div(
+  h1(() => `Count: ${count}`),
+  button('Increment', on('click', () => { count++; update(); })),
+  button('Reset', on('click', () => { count = 0; update(); }))
+);
+
+render(app, document.body);
+```
+
+### Todo List
+
+```ts
+import 'nuclo';
+
+type Todo = { id: number; text: string; done: boolean };
+
+let todos: Todo[] = [];
+let nextId = 1;
+let inputValue = '';
+
+function addTodo() {
+  if (!inputValue.trim()) return;
+  todos.push({ id: nextId++, text: inputValue, done: false });
+  inputValue = '';
+  update();
+}
+
+const app = div(
+  { className: 'todo-app' },
+
+  // Input
+  div(
+    input({ value: () => inputValue },
+      on('input', e => { inputValue = e.target.value; update(); }),
+      on('keydown', e => e.key === 'Enter' && addTodo())
+    ),
+    button('Add', on('click', addTodo))
+  ),
+
+  // List
+  when(() => todos.length > 0,
+    list(() => todos, (todo) =>
+      div(
+        { className: () => todo.done ? 'done' : '' },
+        input({ type: 'checkbox', checked: () => todo.done },
+          on('change', () => { todo.done = !todo.done; update(); })
+        ),
+        span(() => todo.text),
+        button('×', on('click', () => {
+          todos = todos.filter(t => t.id !== todo.id);
+          update();
+        }))
+      )
+    )
+  ).else(
+    p('No todos yet!')
+  )
+);
+
+render(app, document.body);
+```
+
+### Real-time Search Filter
+
+```ts
+import 'nuclo';
+
+const users = [
+  { id: 1, name: 'Alice Johnson', email: 'alice@example.com' },
+  { id: 2, name: 'Bob Smith', email: 'bob@example.com' },
+  { id: 3, name: 'Charlie Brown', email: 'charlie@example.com' }
+];
+
+let searchQuery = '';
+
+function filteredUsers() {
+  const q = searchQuery.toLowerCase();
+  return users.filter(u =>
+    u.name.toLowerCase().includes(q) ||
+    u.email.toLowerCase().includes(q)
+  );
+}
+
+const app = div(
+  h1('User Directory'),
+
+  input(
+    {
+      type: 'search',
+      placeholder: 'Search users...',
+      value: () => searchQuery
+    },
+    on('input', e => {
+      searchQuery = e.target.value;
+      update();
+    })
+  ),
+
+  when(() => filteredUsers().length > 0,
+    list(() => filteredUsers(), user =>
+      div(
+        { className: 'user-card' },
+        h3(user.name),
+        p(user.email)
+      )
+    )
+  ).else(
+    p(() => `No users found for "${searchQuery}"`)
+  )
+);
+
+render(app, document.body);
+```
+
+### Loading States & Async
+
+```ts
+import 'nuclo';
+
+type Product = { id: number; title: string; category: string };
+type State = { status: 'idle' | 'loading' | 'error'; products: Product[]; error?: string };
+
+const state: State = { status: 'idle', products: [] };
+let searchQuery = 'phone';
+
+async function fetchProducts() {
+  if (!searchQuery.trim()) return;
+
+  state.status = 'loading';
+  update();
+
+  try {
+    const response = await fetch(`https://dummyjson.com/products/search?q=${searchQuery}`);
+    const data = await response.json();
+    state.products = data.products;
+    state.status = 'idle';
+  } catch (err) {
+    state.status = 'error';
+    state.error = err.message;
+  }
+  update();
+}
+
+const app = div(
+  div(
+    input(
+      {
+        type: 'search',
+        placeholder: 'Search products...',
+        value: () => searchQuery
+      },
+      on('input', e => {
+        searchQuery = e.target.value;
+        update();
+      }),
+      on('keydown', e => e.key === 'Enter' && fetchProducts())
+    ),
+    button('Search', on('click', fetchProducts))
+  ),
+
+  when(() => state.status === 'loading',
+    div('Loading...')
+  ).when(() => state.status === 'error',
+    div({ className: 'error' }, () => `Error: ${state.error}`)
+  ).when(() => state.products.length > 0,
+    list(() => state.products, product =>
+      div(
+        { className: 'product-card' },
+        h3(product.title),
+        p(() => `Category: ${product.category}`)
+      )
+    )
+  ).else(
+    div('Click search to load products')
+  )
+);
+
+render(app, document.body);
+```
+
+---
+
+## Core Concepts
+
+### 1. **Explicit Updates**
+
+nuclo doesn't auto-detect changes. You call `update()` when ready:
+
+```ts
+let name = 'World';
+
+// Mutate freely
+name = 'Alice';
+name = name.toUpperCase();
+
+// Update once when ready
+update();
+```
+
+**Advantages of explicit `update()`:**
+
+- **Performance**: Batch multiple mutations into a single update cycle
+- **Control**: You decide exactly when the UI should refresh
+- **Predictability**: Zero surprise re-renders, explicit update flow
+- **Simplicity**: No proxies, no dependency graphs, just objects and functions
+- **Debugging**: Set a breakpoint at `update()` to trace all state changes
+
+```ts
+// Example: Batch updates for better performance
+items.push(item1);
+items.push(item2);
+items.sort();
+user.name = 'Alice';
+update();  // One update for all changes
+
+// vs. automatic tracking (hypothetical)
+items.push(item1);  // triggers update
+items.push(item2);  // triggers update
+items.sort();       // triggers update
+user.name = 'Alice'; // triggers update
+// 4 updates instead of 1!
+```
+
+### 2. **Dynamic Functions**
+
+Zero-arg functions become dynamic bindings that re-run when you call `update()`:
+
+```ts
+let count = 0;
+
+div(
+  () => `Count: ${count}`,  // Updates when update() is called
+  { title: () => `Current: ${count}` }  // Attributes too
+)
+```
+
+### 3. **Conditional Rendering with `when`**
+
+First matching condition wins:
+
+```ts
+when(() => user.isAdmin,
+  div('Admin Panel')
+).when(() => user.isLoggedIn,
+  div('User Dashboard')
+).else(
+  div('Please log in')
+)
+```
+
+DOM is preserved if the active branch doesn't change.
+
+### 4. **List Synchronization**
+
+Lists use object identity (not keys) to track items:
+
+```ts
+list(() => items, (item, index) =>
+  div(() => `${index}: ${item.name}`)
+)
+```
+
+Mutate the array (push, splice, reverse), then call `update()`. Elements are reused if the item reference is the same.
+
+## API Reference
+
+### Core Functions
+
+#### `update()`
+
+Runs one synchronous update pass across every dynamic binding. Call this after mutating state:
+
+```ts
+count++;
+items.push(newItem);
+update();
+```
+
+#### `list(provider, renderer)`
+
+Synchronizes an array to DOM elements:
+
+```ts
+list(
+  () => items,           // Provider function
+  (item, index) => div(  // Renderer
+    () => `${index}: ${item.name}`
+  )
+)
+```
+
+Items are tracked by object identity. Mutate the array and call `update()` to sync.
+
+#### `when(condition, ...content)`
+
+Conditional rendering with chaining:
+
+```ts
+when(() => count > 10,
+  div('High')
+).when(() => count > 0,
+  div('Low')
+).else(
+  div('Zero')
+)
+```
+
+First matching condition wins. DOM is preserved if the active branch doesn't change.
+
+#### `on(event, handler, options?)`
+
+Attach event listeners:
+
+```ts
+button('Click me',
+  on('click', () => console.log('clicked')),
+  on('mouseenter', handleHover, { passive: true })
+)
+```
+
+#### `scope(...ids)`
+
+Registers an element as a named update root, so `update("id")` re-runs only the dynamic bindings contained within it instead of the whole page:
+
+```ts
+div(
+  scope('cart'),
+  span(() => `Items: ${cartItems.length}`)
+)
+
+cartItems.push(nextItem);
+update('cart'); // only updates runtimes inside the "cart" scope
+```
+
+### Tag Builders
+
+All HTML and SVG tags are available globally:
+
+```ts
+div(), span(), button(), input(), h1(), p(), ul(), li()
+svgSvg(), circleSvg(), pathSvg(), rectSvg(), gSvg()
+// ... 175 HTML and SVG builders total
+```
+
+### Attributes
+
+Pass attributes as objects:
+
+```ts
+div('Hello', {
+  className: 'container',
+  id: 'main',
+  'data-test': 'value',
+  style: { color: 'red', fontSize: '16px' }
+})
+```
+
+Dynamic attributes use functions:
+
+```ts
+div({
+  className: () => isActive ? 'active' : '',
+  disabled: () => !isValid,
+  style: () => ({ opacity: isVisible ? 1 : 0 })
+})
+```
+
+### Styling
+
+Nuclo includes an atomic CSS-in-TS engine. `css()` is available globally after `import 'nuclo'`. For theming and responsive breakpoints use `createCss()`:
+
+```ts
+import 'nuclo';
+
+const { css } = createCss({
+  colors: { primary: '#14b8a6' },
+  screens: { md: '(min-width: 768px)' },
+});
+
+const card = css({
+  p: 16,
+  rounded: 8,
+  md: { p: 24 },
+  hover: { borderColor: 'primary' },
+});
+
+const el = div(card, 'Hello');
+```
+
+`css()` returns an object with a `className` key that can be passed directly to any tag builder. Global styles and keyframe animations use `globalStyle()` and `keyframes()`.
+
+#### Composing with `cx()`
+
+`cx()` composes styles with exact, last-wins conflict resolution — because the engine knows which declaration every class it minted represents, a later `color` atom drops the earlier one (no tailwind-merge guessing). It accepts results, raw class strings, falsy values, and nested arrays:
+
+```ts
+cx(base, isActive && activeStyle);          // conditional
+cx([base, isActive && activeStyle], extra); // arrays are flattened
+```
+
+#### Typed variants with `variants()`
+
+`variants()` turns a base style plus named variant groups into a strongly-typed recipe. Variant names and values are inferred, so selecting an unknown one is a compile error, and `true`/`false` value groups are selected with real booleans. Every variant compiles to atomic classes once at definition time; a call is a cached lookup plus a `cx()` merge.
+
+```ts
+import 'nuclo';
+
+const { variants } = createCss({
+  colors: { primary: '#6366f1', danger: '#ef4444' },
+});
+
+const button = variants({
+  base: { rounded: 8, weight: 600, cursor: 'pointer' },
+  variants: {
+    intent: {
+      primary: { bg: 'primary', color: '#fff' },
+      danger:  { bg: 'danger',  color: '#fff' },
+    },
+    size: {
+      sm: { px: 10, py: 6,  text: 14 },
+      lg: { px: 18, py: 12, text: 16 },
+    },
+    block: { true: { display: 'block', w: '100%' } },
+  },
+  defaultVariants: { intent: 'primary', size: 'sm' },
+  compoundVariants: [
+    { intent: 'danger', size: 'lg', css: { weight: 700 } },
+  ],
+});
+
+div(button({ intent: 'danger', size: 'lg' }), 'Delete'); // StyleResult — drop-in attributes
+div(button(), 'Save');                                    // uses defaultVariants
+
+button({ intent: 'ghost' }); // ✗ compile error: "ghost" is not a defined intent
+```
+
+The result is a `StyleResult`, so it drops straight into any tag builder or composes further with `cx(button({ size: 'lg' }), extraClass)`.
+
+### Server-Side Rendering
+
+Import `nuclo/polyfill` before `nuclo` in your Node.js server entry, then use `renderToString()` and `getCssText()` from `nuclo/ssr`:
+
+```ts
+import 'nuclo/polyfill';
+import 'nuclo';
+import { renderToString, getCssText } from 'nuclo/ssr';
+import { App } from './app.ts';
+
+const html = renderToString(App());
+const styles = getCssText();
+
+const page = `<!doctype html><html><head><style>${styles}</style></head>
+<body><div id="app">${html}</div></body></html>`;
+```
+
+On the client, call `hydrate()` instead of `render()` to attach Nuclo runtimes to the existing markup without re-creating DOM nodes.
+
+`nuclo/ssr` also exports `renderManyToString(inputs)` for rendering a batch of trees at once, and `renderToStringWithContainer(input, containerTag?, containerAttrs?)` to wrap the output in a container element without a second serialization pass.
+
+---
+
+## Best Practices
+
+### Batch Updates
+
+Make multiple changes, then update once:
+
+```ts
+// Efficient: One update for all changes
+items.push(item1);
+items.push(item2);
+items.sort();
+update();
+
+// Works but inefficient: Multiple updates
+items.push(item1);
+update();
+items.push(item2);
+update();
+```
+
+### Object Identity for Lists
+
+Lists track items by reference. Mutate objects in place:
+
+```ts
+// Good: Mutate the object
+todos[0].done = true;
+update();
+
+// Avoid: Creates new object, DOM element recreated
+todos[0] = { ...todos[0], done: true };
+update();
+```
+
+### Use `.else()` for Clarity
+
+Even if not initially needed:
+
+```ts
+when(() => isLoading,
+  div('Loading...')
+).else(
+  div('Ready')  // Clear intent
+)
+```
+
+---
+
+## Advanced Patterns
+
+### Nested Structures
+
+Combine `when` and `list`:
+
+```ts
+when(() => user.isLoggedIn,
+  div(
+    h1(() => `Welcome, ${user.name}`),
+    list(() => user.notifications, n =>
+      div(n.message, { className: () => n.read ? 'read' : 'unread' })
+    )
+  )
+).else(
+  div('Please log in')
+)
+```
+
+### Component-like Functions
+
+```ts
+function UserCard(user: User) {
+  return div(
+    { className: 'user-card' },
+    img({ src: user.avatar }),
+    h3(user.name),
+    p(user.bio)
+  );
+}
+
+list(() => users, user => UserCard(user))
+```
+
+### Computed Values
+
+```ts
+function activeCount() {
+  return todos.filter(t => !t.done).length;
+}
+
+div(
+  () => `${activeCount()} remaining`
+)
+```
+
+---
+
+## Performance
+
+- **No virtual DOM diffing** – Direct DOM manipulation for maximum efficiency
+- **Fine-grained updates** – Only updates what changed, nothing more
+- **Element reuse** – Lists intelligently reuse DOM elements when items move
+- **Branch preservation** – Conditional branches persist until conditions change
+
+For high-frequency updates (animations, game loops), batch mutations before calling `update()`.
+
+---
+
+## Debugging
+
+### Inspect Markers
+
+Open DevTools to see comment markers that help you understand the structure:
+
+```html
+<!-- when-start-1 -->
+<div>Content</div>
+<!-- when-end -->
+
+<!-- list-start-2 -->
+<div>Item 1</div>
+<div>Item 2</div>
+<!-- list-end -->
+```
+
+These markers identify conditional and list boundaries in the DOM.
+
+### Common Issues
+
+**Content not updating?**
+- Ensure you're calling `update()` after state changes
+- Verify your dynamic functions are returning the expected values — functions that return `null`/`undefined` render as empty text and fill in on the next `update()`
+
+**List items not reusing elements?**
+- Keep object references stable (mutate instead of replacing)
+- Avoid creating new objects when updating properties
+
+### Gotchas
+
+**Parameter count decides what a function modifier means.**
+A modifier with **zero declared parameters** is treated as reactive text (or a reactive `cn()` className) and is called with no arguments. A modifier with **one or more declared parameters** is a node-modifier function receiving `(element, index)`. Default and rest parameters don't count as declared parameters (`fn.length` is 0), so these are all treated as *reactive text*, not node modifiers:
+
+```ts
+div((el = fallback) => el.id);   // reactive text — el is undefined!
+div((...args) => args[0]);       // reactive text — args is empty!
+div((el) => el.id = "x");        // node modifier — el is the element ✓
+```
+
+If a modifier needs the element, declare it as a plain required parameter.
+
+**Detached nodes lose reactivity.**
+Reactive registrations (text, attributes, `list()`, `when()`) are pruned for any node that is disconnected from the DOM when `update()` runs. Re-attaching the node later does **not** restore them. Keep-alive and portal-style patterns should re-render content after re-attaching instead of moving live subtrees between updates.
+
+---
+
+## Documentation
+
+Full documentation is available at [https://nuclo.dev/](https://nuclo.dev/)
+
+- [Getting Started](https://nuclo.dev/getting-started)
+- [API Reference](https://nuclo.dev/core-api)
+- [Examples](https://nuclo.dev/examples)
+
+---
+
+## Author
+
+Created by **Danilo Celestino de Castro**
+
+- GitHub: [@dan2dev](https://github.com/dan2dev)
+- Twitter: [@dan2dev](https://twitter.com/dan2dev)
+
+---
+
+## License
+
+MIT License - see [LICENSE.md](LICENSE.md) for details.
+
+This library is free and open source. When using nuclo, please include attribution in your documentation or application.
+
+**TL;DR:** Use it freely, give credit where it's due!