From 3fe05d40e6e9d6a37af1e28005b011e883fa5e87 Mon Sep 17 00:00:00 2001 From: natxocc Date: Thu, 14 May 2026 14:21:21 +0200 Subject: [PATCH] Update docs --- docs/_sidebar.md | 4 +- docs/api/quick.md | 63 -------------------- docs/api/tags.md | 139 ++----------------------------------------- docs/install.md | 147 ++++++++++++---------------------------------- 4 files changed, 45 insertions(+), 308 deletions(-) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 99a1ec8..12064ac 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -18,4 +18,6 @@ * [Global Store](api/global.md) * [JSX Style](api/jsx.md) * [HTML converter](convert.md) - * [UI](ui.md) \ No newline at end of file + +* **UI** + * [WIP] \ No newline at end of file diff --git a/docs/api/quick.md b/docs/api/quick.md index daec944..d0e937d 100644 --- a/docs/api/quick.md +++ b/docs/api/quick.md @@ -26,24 +26,6 @@ count(5) // triggers log: count=5, double=10 --- -### `$$(object)` – Deep Reactive Proxy - -Makes a plain object (and all nested objects) deeply reactive. Any property access is tracked, any mutation triggers updates. - -```javascript -const state = $$({ user: { name: 'Alice', age: 30 }, items: [1,2,3] }) - -watch(() => { - console.log(state.user.name) // tracks `user.name` -}) - -state.user.name = 'Bob' // triggers the effect -``` - -> **Note**: `$$` caches proxies per original object, so calling `$$` multiple times on the same object returns the same proxy. - ---- - ### `watch(source, callback?)` – Reactive Effect Two modes: @@ -99,18 +81,6 @@ h('div', {}, [ Tag helpers **are exported** from the core. -```javascript -import "sigpro" - -// You can now write: -div({ class: 'container' }, [ - h1({}, 'Title'), - button({ onClick: () => alert('hi') }, 'Click me') -]) -``` - -In the **IIFE bundle** (`sigpro.min.js`), the helpers are already injected globally – no import needed. - Available tags: `a`, `abbr`, `article`, `aside`, `audio`, `b`, `blockquote`, `br`, `button`, `canvas`, `caption`, `cite`, `code`, `col`, `colgroup`, `datalist`, `dd`, `del`, `details`, `dfn`, `dialog`, `div`, `dl`, `dt`, `em`, `embed`, `fieldset`, `figcaption`, `figure`, `footer`, `form`, `h1`…`h6`, `header`, `hr`, `i`, `iframe`, `img`, `input`, `ins`, `kbd`, `label`, `legend`, `li`, `main`, `mark`, `meter`, `nav`, `object`, `ol`, `optgroup`, `option`, `output`, `p`, `picture`, `pre`, `progress`, `section`, `select`, `slot`, `small`, `source`, `span`, `strong`, `sub`, `summary`, `sup`, `svg`, `table`, `tbody`, `td`, `template`, `textarea`, `tfoot`, `th`, `thead`, `time`, `tr`, `u`, `ul`, `video`. --- @@ -162,39 +132,6 @@ batch(() => { }) ``` ---- - -## Router – `router(routes)` - -Hash‑based SPA router. Returns a DOM node that renders the current route. - -```javascript -import { router } from 'sigpro/router' // import router - -const routes = [ - { path: '/', component: () => div({}, 'Home') }, - { path: '/user/:id', component: (params) => div({}, `User ${params.id}`) }, - { path: '*', component: () => div({}, '404') } -] - -const App = () => div({}, [ - a({ href: '#/' }, 'Home'), - a({ href: '#/user/42' }, 'User 42'), - router(routes) -]) -``` - -**API** - -| Method | Description | -|--------|-------------| -| `router.params()` | Returns a reactive signal of current route params (e.g., `{ id: '42' }`). | -| `router.to(path)` | Navigate to a new hash (e.g., `router.to('/user/5')`). Prepend `#` automatically. | -| `router.back()` | Go back in history. | -| `router.path()` | Returns current hash path without `#` (e.g., `/user/42`). | - ---- - ## Mounting – `mount(component, target)` Clears the target element and mounts the application. Returns the runtime instance (which has a `.destroy()` method). diff --git a/docs/api/tags.md b/docs/api/tags.md index 6f2195b..493c6ba 100644 --- a/docs/api/tags.md +++ b/docs/api/tags.md @@ -10,39 +10,13 @@ SigPro creates a wrapper function for each standard HTML tag. > **Note:** All tag helpers are **lowercase** (e.g., `div`, `span`, `button`) and can be used directly once globally enabled. ---- - -## 2. Activating the Tag Helpers - -Depending on how you load SigPro, the activation varies: - -### A. Classic IIFE – Automatic Global Helpers -When you use the **IIFE bundle** (`sigpro.js` or `sigpro.min.js`) with a traditional ` - -``` - -### B. ESM (Modern JavaScript) – Explicit Activation -**ES module** (`import { ... } from 'sigpro'`). - -```js -import { ... } from 'sigpro'; - -// Now you can use helpers globally -const App = () => div({ class: "app" }, "Ready!"); -``` - > If you prefer to avoid globals, you can always use `h('div', ...)` directly—it’s perfectly fine. +> **Auto‑cleanup:** All tag helpers and `h` automatically dispose effects, event listeners, and nested components when removed from the DOM. + --- -## 3. The Complete List of Tag Helpers +## 2. The Complete List of Tag Helpers All helpers are **lowercase** and follow HTML5 tag names. @@ -59,7 +33,7 @@ Full list: `a`, `abbr`, `article`, `aside`, `audio`, `b`, `blockquote`, `br`, `b --- -## 4. Usage Patterns +## 3. Usage Patterns ### A. Attributes + Children @@ -83,54 +57,7 @@ section([ --- -## 5. Reactive Power - -These helpers are natively wired into SigPro's reactivity system. - -### Reactive Attributes (One‑Way) - -Pass a **function** that returns the value. SigPro creates an internal effect to keep the DOM in sync. - -```javascript -const theme = $("light"); - -div({ - class: () => `app-box ${theme()}` -}, "Themeable Box"); -``` - -### Two‑Way Binding (Automatic) - -Assign a **signal** directly to `value` or `checked` on form inputs – SigPro automatically bridges the signal and the input element bidirectionally. - -```javascript -const search = $(""); - -input({ - type: "text", - placeholder: "Search...", - value: search -}); -``` - -> **Pro Tip:** To make an input **read‑only** but still reactive, wrap the signal in a function: `value: () => search()` – this prevents backward synchronization. - -### Dynamic Children - -You can pass a **function as a child** – it will be re‑executed whenever any signal inside changes, and the DOM will be patched surgically. - -```javascript -const count = $(0); - -div([ - p(() => `Count is ${count()}`), - button({ onClick: () => count(count() + 1) }, "Increment") -]); -``` - ---- - -## 6. Custom Components with `h()` or Tag Helpers +## 4. Custom Components with `h()` or Tag Helpers While the tag helpers cover all standard HTML tags, you can create reusable components using them directly. @@ -170,58 +97,4 @@ const Timer = () => { return el; }; -``` - ---- - -## 7. Comparison with `h()` - -| Use case | Recommendation | -| :--- | :--- | -| Standard tags (`div`, `span`, `button`) | Use tag helpers: `div()`, `span()`, `button()` | -| Dynamic tag names (unknown at write time) | Use `h(tagName, props, children)` | -| Components returning a single node | Any function that returns a node (using helpers or `h`) | - -> **Auto‑cleanup:** All tag helpers and `h` automatically dispose effects, event listeners, and nested components when removed from the DOM. - ---- - -## 8. Complete Example - -### ESM (modern projects) - -```javascript -import { $, mount } from 'sigpro'; - -const nameSignal = $(''); - -const App = () => - div({ class: "app" }, [ - h1("Welcome"), - input({ - placeholder: "Your name", - value: nameSignal - }), - p(() => `Hello, ${nameSignal() || "stranger"}!`), - button({ onClick: () => alert("Clicked") }, "Click me") - ]); - -mount(App, '#app'); -``` - -### Classic IIFE (auto‑global) - -```html - - -``` - +``` \ No newline at end of file diff --git a/docs/install.md b/docs/install.md index a56db9f..4795873 100644 --- a/docs/install.md +++ b/docs/install.md @@ -12,67 +12,32 @@ Choose the method that best fits your workflow: ```bash npm install sigpro -``` - +or - -
- -```bash -pnpm add sigpro -``` - -
- - -
- -```bash -yarn add sigpro -``` - -
- - -
- -```bash bun add sigpro ```
- +
```html -``` - -
- - -
- -```html - - - ``` @@ -91,7 +56,7 @@ SigPro uses **lowercase** Tag Helpers (e.g., `div`, `button`) to keep the syntax ```javascript // App.js – Use named imports for the core, activate helpers if needed -import { $, mount } from 'sigpro'; +import { $, mount } from "sigpro"; const App = () => { const count = $(0); @@ -99,12 +64,12 @@ const App = () => { h1(() => `Count is: ${count()}`), button( { class: "btn btn-primary", onclick: () => count(count() + 1) }, - "Increment" + "Increment", ), ]); }; -mount(App, '#app'); +mount(App, "#app"); ```
@@ -118,20 +83,22 @@ mount(App, '#app');
- - - @@ -142,56 +109,14 @@ mount(App, '#app'); --- -## 3. Global by Design (Two Modes) +## 3. Why no build step? -SigPro gives you full control over global pollution. - -### Mode A: Classic (IIFE) – Full Auto‑injection -When you load the **IIFE full bundle** (`sigpro.min.js`) with a traditional `