Include if for in Docs
This commit is contained in:
@@ -17,7 +17,7 @@
|
||||
</head>
|
||||
<body>
|
||||
<div id="app"></div>
|
||||
<script>window.__VP_HASH_MAP__=JSON.parse("{\"api_html.md\":\"DSCIaSlE\",\"api_mount.md\":\"CoM2SFqU\",\"api_quick.md\":\"Dw-DUc7L\",\"api_router.md\":\"Cn98LjXO\",\"api_signal.md\":\"BmorvARW\",\"api_tags.md\":\"BKWIb8mV\",\"api_watch.md\":\"BEM6Qssx\",\"index.md\":\"By6smViD\",\"install.md\":\"HK-a2_Fb\",\"ui_quick.md\":\"CsppjR8J\",\"vite_plugin.md\":\"CTs8LDIL\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"SigPro\",\"description\":\"Minimalist Reactive Library\",\"base\":\"/sigpro/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/logo.svg\",\"nav\":[{\"text\":\"Home\",\"link\":\"/\"},{\"text\":\"Install\",\"link\":\"/install\"},{\"text\":\"Api\",\"link\":\"/api/quick\"}],\"sidebar\":[{\"text\":\"Introduction\",\"items\":[{\"text\":\"Installation\",\"link\":\"/install\"},{\"text\":\"Vite Plugin\",\"link\":\"/vite/plugin\"}]},{\"text\":\"API Reference\",\"items\":[{\"text\":\"Quick Start\",\"link\":\"/api/quick\"},{\"text\":\"$\",\"link\":\"/api/signal\"},{\"text\":\"$.watch\",\"link\":\"/api/watch\"},{\"text\":\"$.html\",\"link\":\"/api/html\"},{\"text\":\"$.router\",\"link\":\"/api/router\"},{\"text\":\"$.mount\",\"link\":\"/api/mount\"},{\"text\":\"Tags\",\"link\":\"/api/tags\"}]},{\"text\":\"UI Components\",\"items\":[{\"text\":\"Quick Start\",\"link\":\"/ui/quick\"}]}],\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/natxocc/sigpro\"}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
|
||||
<script>window.__VP_HASH_MAP__=JSON.parse("{\"api_for.md\":\"CGMDz0Px\",\"api_html.md\":\"DSCIaSlE\",\"api_if.md\":\"C-36XjK0\",\"api_mount.md\":\"CoM2SFqU\",\"api_quick.md\":\"D3C2EJww\",\"api_router.md\":\"Cn98LjXO\",\"api_signal.md\":\"BmorvARW\",\"api_tags.md\":\"BKWIb8mV\",\"api_watch.md\":\"BEM6Qssx\",\"index.md\":\"By6smViD\",\"install.md\":\"C1tyiPaQ\",\"ui_quick.md\":\"CsppjR8J\",\"vite_plugin.md\":\"CTs8LDIL\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"SigPro\",\"description\":\"Minimalist Reactive Library\",\"base\":\"/sigpro/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"logo\":\"/logo.svg\",\"nav\":[{\"text\":\"Home\",\"link\":\"/\"},{\"text\":\"Install\",\"link\":\"/install\"},{\"text\":\"Api\",\"link\":\"/api/quick\"}],\"sidebar\":[{\"text\":\"Introduction\",\"items\":[{\"text\":\"Installation\",\"link\":\"/install\"},{\"text\":\"Vite Plugin\",\"link\":\"/vite/plugin\"}]},{\"text\":\"API Reference\",\"items\":[{\"text\":\"Quick Start\",\"link\":\"/api/quick\"},{\"text\":\"$\",\"link\":\"/api/signal\"},{\"text\":\"$.watch\",\"link\":\"/api/watch\"},{\"text\":\"$.if\",\"link\":\"/api/if\"},{\"text\":\"$.for\",\"link\":\"/api/for\"},{\"text\":\"$.router\",\"link\":\"/api/router\"},{\"text\":\"$.mount\",\"link\":\"/api/mount\"},{\"text\":\"$.html\",\"link\":\"/api/html\"},{\"text\":\"Tags\",\"link\":\"/api/tags\"}]},{\"text\":\"UI Components\",\"items\":[{\"text\":\"Quick Start\",\"link\":\"/ui/quick\"}]}],\"socialLinks\":[{\"icon\":\"github\",\"link\":\"https://github.com/natxocc/sigpro\"}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
44
docs/api/for.html
Normal file
44
docs/api/for.html
Normal file
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
44
docs/api/if.html
Normal file
44
docs/api/if.html
Normal file
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
19
docs/assets/api_for.md.CGMDz0Px.js
Normal file
19
docs/assets/api_for.md.CGMDz0Px.js
Normal file
@@ -0,0 +1,19 @@
|
||||
import{_ as i,o as t,c as a,ae as e}from"./chunks/framework.C8AWLET_.js";const g=JSON.parse('{"title":"♻️ Reactive Lists: $.for( )","description":"","frontmatter":{},"headers":[],"relativePath":"api/for.md","filePath":"api/for.md"}'),n={name:"api/for.md"};function l(h,s,r,p,k,d){return t(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="♻️-reactive-lists-for" tabindex="-1">♻️ Reactive Lists: <code>$.for( )</code> <a class="header-anchor" href="#♻️-reactive-lists-for" aria-label="Permalink to "♻️ Reactive Lists: \`$.for( )\`""></a></h1><p>The <code>$.for</code> function is a high-performance list renderer. It maps an array (or a Signal containing an array) to DOM nodes. Unlike a simple <code>.map()</code>, <code>$.for</code> is <strong>keyed</strong>, meaning it only updates, moves, or deletes the specific items that changed.</p><h2 id="🛠️-function-signature" tabindex="-1">🛠️ Function Signature <a class="header-anchor" href="#🛠️-function-signature" aria-label="Permalink to "🛠️ Function Signature""></a></h2><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> source: Signal</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">any[]</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Function </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> any[], </span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> render: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">item</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> any</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">index</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> HTMLElement, </span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> keyFn: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">item</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> any</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">index</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> number</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> string </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> number</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">): HTMLElement</span></span></code></pre></div><table tabindex="0"><thead><tr><th style="text-align:left;">Parameter</th><th style="text-align:left;">Type</th><th style="text-align:left;">Required</th><th style="text-align:left;">Description</th></tr></thead><tbody><tr><td style="text-align:left;"><strong><code>source</code></strong></td><td style="text-align:left;"><code>Signal</code></td><td style="text-align:left;">Yes</td><td style="text-align:left;">The reactive array to iterate over.</td></tr><tr><td style="text-align:left;"><strong><code>render</code></strong></td><td style="text-align:left;"><code>Function</code></td><td style="text-align:left;">Yes</td><td style="text-align:left;">A function that returns a component or Node for each item.</td></tr><tr><td style="text-align:left;"><strong><code>keyFn</code></strong></td><td style="text-align:left;"><code>Function</code></td><td style="text-align:left;">Yes</td><td style="text-align:left;">A function to extract a <strong>unique ID</strong> for each item (crucial for performance).</td></tr></tbody></table><p><strong>Returns:</strong> A <code>div</code> element with <code>display: contents</code> containing the live list.</p><hr><h2 id="📖-usage-patterns" tabindex="-1">📖 Usage Patterns <a class="header-anchor" href="#📖-usage-patterns" aria-label="Permalink to "📖 Usage Patterns""></a></h2><h3 id="_1-basic-keyed-list" tabindex="-1">1. Basic Keyed List <a class="header-anchor" href="#_1-basic-keyed-list" aria-label="Permalink to "1. Basic Keyed List""></a></h3><p>Always use a unique property (like an <code>id</code>) as a key to ensure SigPro doesn't recreate nodes unnecessarily.</p><div class="language-javascript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">javascript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> users</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> $</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">([</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { id: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Alice"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { id: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">2</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, name: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Bob"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span>
|
||||
<span class="line"></span>
|
||||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Ul</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ class: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"list"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, [</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> $.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(users, </span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Li</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ class: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"p-2"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, user.name),</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">user</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> user.id</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> )</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span></code></pre></div><h3 id="_2-handling-primitive-arrays" tabindex="-1">2. Handling Primitive Arrays <a class="header-anchor" href="#_2-handling-primitive-arrays" aria-label="Permalink to "2. Handling Primitive Arrays""></a></h3><p>If your array contains simple strings or numbers, you can use the value itself or the index as a key (though the index is less efficient for reordering).</p><div class="language-javascript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">javascript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> tags</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> $</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">([</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Tech"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"JS"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Web"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span>
|
||||
<span class="line"></span>
|
||||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Div</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ class: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"flex gap-1"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, [</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> $.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">for</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(tags, (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">tag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Badge</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(tag), (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">tag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> tag)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span></code></pre></div><hr><h2 id="🏗️-how-it-works-the-reconciliation" tabindex="-1">🏗️ How it Works (The Reconciliation) <a class="header-anchor" href="#🏗️-how-it-works-the-reconciliation" aria-label="Permalink to "🏗️ How it Works (The Reconciliation)""></a></h2><p>When the <code>source</code> signal changes, <code>$.for</code> performs the following steps:</p><ol><li><strong>Key Diffing</strong>: It compares the new keys with the previous ones stored in an internal <code>Map</code>.</li><li><strong>Node Reuse</strong>: If a key already exists, the DOM node is <strong>reused</strong> and moved to its new position. No new elements are created.</li><li><strong>Cleanup</strong>: If a key disappears from the list, SigPro calls <code>.destroy()</code> on that specific item's instance. This stops all its internal watchers and removes its DOM nodes.</li></ol><hr><h2 id="💡-performance-tips" tabindex="-1">💡 Performance Tips <a class="header-anchor" href="#💡-performance-tips" aria-label="Permalink to "💡 Performance Tips""></a></h2><ul><li><strong>Stable Keys</strong>: Never use <code>Math.random()</code> as a key. This will force SigPro to destroy and recreate the entire list on every update, killing performance.</li><li><strong>Component Encapsulation</strong>: If each item in your list has its own complex internal state, <code>$.for</code> ensures that state is preserved even if the list is reordered, as long as the key remains the same.</li></ul><hr><h2 id="🧪-summary-comparison" tabindex="-1">🧪 Summary Comparison <a class="header-anchor" href="#🧪-summary-comparison" aria-label="Permalink to "🧪 Summary Comparison""></a></h2><table tabindex="0"><thead><tr><th style="text-align:left;">Feature</th><th style="text-align:left;">Standard <code>Array.map</code></th><th style="text-align:left;">SigPro <code>$.for</code></th></tr></thead><tbody><tr><td style="text-align:left;"><strong>Re-render</strong></td><td style="text-align:left;">Re-renders everything</td><td style="text-align:left;">Only updates changes</td></tr><tr><td style="text-align:left;"><strong>DOM Nodes</strong></td><td style="text-align:left;">Re-created every time</td><td style="text-align:left;"><strong>Reused via Keys</strong></td></tr><tr><td style="text-align:left;"><strong>Memory</strong></td><td style="text-align:left;">Potential leaks</td><td style="text-align:left;"><strong>Automatic Cleanup</strong></td></tr><tr><td style="text-align:left;"><strong>State</strong></td><td style="text-align:left;">Lost on re-render</td><td style="text-align:left;"><strong>Preserved per item</strong></td></tr></tbody></table>`,24)])])}const E=i(n,[["render",l]]);export{g as __pageData,E as default};
|
||||
1
docs/assets/api_for.md.CGMDz0Px.lean.js
Normal file
1
docs/assets/api_for.md.CGMDz0Px.lean.js
Normal file
@@ -0,0 +1 @@
|
||||
import{_ as i,o as t,c as a,ae as e}from"./chunks/framework.C8AWLET_.js";const g=JSON.parse('{"title":"♻️ Reactive Lists: $.for( )","description":"","frontmatter":{},"headers":[],"relativePath":"api/for.md","filePath":"api/for.md"}'),n={name:"api/for.md"};function l(h,s,r,p,k,d){return t(),a("div",null,[...s[0]||(s[0]=[e("",24)])])}const E=i(n,[["render",l]]);export{g as __pageData,E as default};
|
||||
19
docs/assets/api_if.md.C-36XjK0.js
Normal file
19
docs/assets/api_if.md.C-36XjK0.js
Normal file
@@ -0,0 +1,19 @@
|
||||
import{_ as i,o as t,c as a,ae as e}from"./chunks/framework.C8AWLET_.js";const g=JSON.parse('{"title":"🔀 Reactive Branching: $.if( )","description":"","frontmatter":{},"headers":[],"relativePath":"api/if.md","filePath":"api/if.md"}'),n={name:"api/if.md"};function l(h,s,p,r,o,d){return t(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="🔀-reactive-branching-if" tabindex="-1">🔀 Reactive Branching: <code>$.if( )</code> <a class="header-anchor" href="#🔀-reactive-branching-if" aria-label="Permalink to "🔀 Reactive Branching: \`$.if( )\`""></a></h1><p>The <code>$.if</code> function is a reactive control flow operator. It manages the conditional rendering of components, ensuring that only the active branch exists in the DOM and in memory.</p><h2 id="🛠️-function-signature" tabindex="-1">🛠️ Function Signature <a class="header-anchor" href="#🛠️-function-signature" aria-label="Permalink to "🛠️ Function Signature""></a></h2><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> condition: Signal</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">boolean</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Function, </span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> thenVal: Component </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Node, </span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> otherwiseVal</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Component </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Node</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">): HTMLElement</span></span></code></pre></div><table tabindex="0"><thead><tr><th style="text-align:left;">Parameter</th><th style="text-align:left;">Type</th><th style="text-align:left;">Required</th><th style="text-align:left;">Description</th></tr></thead><tbody><tr><td style="text-align:left;"><strong><code>condition</code></strong></td><td style="text-align:left;"><code>Signal</code></td><td style="text-align:left;">Yes</td><td style="text-align:left;">A reactive source that determines which branch to render.</td></tr><tr><td style="text-align:left;"><strong><code>thenVal</code></strong></td><td style="text-align:left;"><code>any</code></td><td style="text-align:left;">Yes</td><td style="text-align:left;">The content to show when the condition is <strong>truthy</strong>.</td></tr><tr><td style="text-align:left;"><strong><code>otherwiseVal</code></strong></td><td style="text-align:left;"><code>any</code></td><td style="text-align:left;">No</td><td style="text-align:left;">The content to show when the condition is <strong>falsy</strong> (defaults to null).</td></tr></tbody></table><p><strong>Returns:</strong> A <code>div</code> element with <code>display: contents</code> that acts as a reactive portal for the branches.</p><hr><h2 id="📖-usage-patterns" tabindex="-1">📖 Usage Patterns <a class="header-anchor" href="#📖-usage-patterns" aria-label="Permalink to "📖 Usage Patterns""></a></h2><h3 id="_1-simple-toggle" tabindex="-1">1. Simple Toggle <a class="header-anchor" href="#_1-simple-toggle" aria-label="Permalink to "1. Simple Toggle""></a></h3><p>The most common use case is showing or hiding a single element based on a state.</p><div class="language-javascript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">javascript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> isVisible</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> $</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
|
||||
<span class="line"></span>
|
||||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Div</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">([</span></span>
|
||||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Button</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">onclick</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> isVisible</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">isVisible</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()) }, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Toggle Message"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> $.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(isVisible, </span></span>
|
||||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> P</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Now you see me!"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">), </span></span>
|
||||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> P</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Now you don't..."</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> )</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span></code></pre></div><h3 id="_2-lazy-component-loading" tabindex="-1">2. Lazy Component Loading <a class="header-anchor" href="#_2-lazy-component-loading" aria-label="Permalink to "2. Lazy Component Loading""></a></h3><p>Unlike using a hidden class (CSS <code>display: none</code>), <code>$.if</code> is <strong>lazy</strong>. The branch that isn't active <strong>is never created</strong>. This saves memory and initial processing time.</p><div class="language-javascript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">javascript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> user.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">isLogged</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Dashboard</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(), </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Only executed if logged in</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> LoginGate</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Only executed if guest</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span></code></pre></div><hr><h2 id="🧹-automatic-cleanup" tabindex="-1">🧹 Automatic Cleanup <a class="header-anchor" href="#🧹-automatic-cleanup" aria-label="Permalink to "🧹 Automatic Cleanup""></a></h2><p>One of the core strengths of <code>$.if</code> is its integrated <strong>Cleanup</strong> logic. SigPro ensures that when a branch is swapped out, it is completely purged.</p><ol><li><strong>Stop Watchers</strong>: All <code>$.watch</code> calls inside the inactive branch are permanently stopped.</li><li><strong>Unbind Events</strong>: Event listeners attached via <code>$.html</code> are removed.</li><li><strong>Recursive Sweep</strong>: SigPro performs a deep "sweep" of the removed branch to ensure no nested reactive effects remain active.</li></ol><hr><h2 id="💡-best-practices" tabindex="-1">💡 Best Practices <a class="header-anchor" href="#💡-best-practices" aria-label="Permalink to "💡 Best Practices""></a></h2><ul><li><strong>Function Wrappers</strong>: If your branches are heavy (e.g., they contain complex components), wrap them in a function <code>() => MyComponent()</code>. This prevents the component from being initialized until the condition actually meets its requirement.</li><li><strong>Logical Expressions</strong>: You can pass a complex computed function as the condition:<div class="language-javascript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">javascript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> count</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 10</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> &&</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> status</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">() </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">===</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'ready'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span></span>
|
||||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Span</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Threshold reached!"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span></code></pre></div></li></ul><hr><h2 id="🏗️-technical-comparison" tabindex="-1">🏗️ Technical Comparison <a class="header-anchor" href="#🏗️-technical-comparison" aria-label="Permalink to "🏗️ Technical Comparison""></a></h2><table tabindex="0"><thead><tr><th style="text-align:left;">Feature</th><th style="text-align:left;">Standard CSS <code>hidden</code></th><th style="text-align:left;">SigPro <code>$.if</code></th></tr></thead><tbody><tr><td style="text-align:left;"><strong>DOM Presence</strong></td><td style="text-align:left;">Always present</td><td style="text-align:left;">Only if active</td></tr><tr><td style="text-align:left;"><strong>Reactivity</strong></td><td style="text-align:left;">Still processing in background</td><td style="text-align:left;"><strong>Paused/Destroyed</strong></td></tr><tr><td style="text-align:left;"><strong>Memory usage</strong></td><td style="text-align:left;">Higher</td><td style="text-align:left;"><strong>Optimized</strong></td></tr><tr><td style="text-align:left;"><strong>Cleanup</strong></td><td style="text-align:left;">Manual</td><td style="text-align:left;"><strong>Automatic</strong></td></tr></tbody></table>`,24)])])}const c=i(n,[["render",l]]);export{g as __pageData,c as default};
|
||||
1
docs/assets/api_if.md.C-36XjK0.lean.js
Normal file
1
docs/assets/api_if.md.C-36XjK0.lean.js
Normal file
@@ -0,0 +1 @@
|
||||
import{_ as i,o as t,c as a,ae as e}from"./chunks/framework.C8AWLET_.js";const g=JSON.parse('{"title":"🔀 Reactive Branching: $.if( )","description":"","frontmatter":{},"headers":[],"relativePath":"api/if.md","filePath":"api/if.md"}'),n={name:"api/if.md"};function l(h,s,p,r,o,d){return t(),a("div",null,[...s[0]||(s[0]=[e("",24)])])}const c=i(n,[["render",l]]);export{g as __pageData,c as default};
|
||||
File diff suppressed because one or more lines are too long
@@ -1,11 +1,11 @@
|
||||
import{_ as i,o as a,c as t,ae as n}from"./chunks/framework.C8AWLET_.js";const g=JSON.parse('{"title":"Installation & Setup","description":"","frontmatter":{},"headers":[],"relativePath":"install.md","filePath":"install.md"}'),l={name:"install.md"};function e(h,s,p,k,r,d){return a(),t("div",null,[...s[0]||(s[0]=[n(`<h1 id="installation-setup" tabindex="-1">Installation & Setup <a class="header-anchor" href="#installation-setup" aria-label="Permalink to "Installation & Setup""></a></h1><p>SigPro is designed to be drop-in ready. Whether you are building a complex application with a bundler or a simple reactive widget in a single HTML file, SigPro scales with your needs.</p><h2 id="_1-installation" tabindex="-1">1. Installation <a class="header-anchor" href="#_1-installation" aria-label="Permalink to "1. Installation""></a></h2><p>Choose the method that best fits your workflow:</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-ugDYB" id="tab-HncsMeJ" checked><label data-title="npm" for="tab-HncsMeJ">npm</label><input type="radio" name="group-ugDYB" id="tab-TR3onma"><label data-title="pnpm" for="tab-TR3onma">pnpm</label><input type="radio" name="group-ugDYB" id="tab-NQ-PUMS"><label data-title="yarn" for="tab-NQ-PUMS">yarn</label><input type="radio" name="group-ugDYB" id="tab-_dK8No0"><label data-title="bun" for="tab-_dK8No0">bun</label><input type="radio" name="group-ugDYB" id="tab-KgTh38z"><label data-title="CDN (ESM)" for="tab-KgTh38z">CDN (ESM)</label></div><div class="blocks"><div class="language-bash vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sigpro</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sigpro</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">yarn</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sigpro</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bun</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sigpro</span></span></code></pre></div><div class="language-html vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">html</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"><</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">script</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"module"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">></span></span>
|
||||
import{_ as i,o as a,c as t,ae as n}from"./chunks/framework.C8AWLET_.js";const g=JSON.parse('{"title":"Installation & Setup","description":"","frontmatter":{},"headers":[],"relativePath":"install.md","filePath":"install.md"}'),l={name:"install.md"};function e(h,s,p,k,r,d){return a(),t("div",null,[...s[0]||(s[0]=[n(`<h1 id="installation-setup" tabindex="-1">Installation & Setup <a class="header-anchor" href="#installation-setup" aria-label="Permalink to "Installation & Setup""></a></h1><p>SigPro is designed to be drop-in ready. Whether you are building a complex application with a bundler or a simple reactive widget in a single HTML file, SigPro scales with your needs.</p><h2 id="_1-installation" tabindex="-1">1. Installation <a class="header-anchor" href="#_1-installation" aria-label="Permalink to "1. Installation""></a></h2><p>Choose the method that best fits your workflow:</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-jUf5_" id="tab-EIaKtz2" checked><label data-title="npm" for="tab-EIaKtz2">npm</label><input type="radio" name="group-jUf5_" id="tab-gYABF9u"><label data-title="pnpm" for="tab-gYABF9u">pnpm</label><input type="radio" name="group-jUf5_" id="tab-9ELi2rW"><label data-title="yarn" for="tab-9ELi2rW">yarn</label><input type="radio" name="group-jUf5_" id="tab-NYQiogX"><label data-title="bun" for="tab-NYQiogX">bun</label><input type="radio" name="group-jUf5_" id="tab-XP8VMaa"><label data-title="CDN (ESM)" for="tab-XP8VMaa">CDN (ESM)</label></div><div class="blocks"><div class="language-bash vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">npm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> install</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sigpro</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sigpro</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">yarn</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sigpro</span></span></code></pre></div><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bun</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> sigpro</span></span></code></pre></div><div class="language-html vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">html</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"><</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">script</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> type</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"module"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">></span></span>
|
||||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Import the core and UI components</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { $ } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'https://cdn.jsdelivr.net/npm/sigpro@latest/+esm'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { UI } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'https://cdn.jsdelivr.net/npm/sigpro@latest/ui/+esm'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> </span></span>
|
||||
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Initialize UI components globally</span></span>
|
||||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> UI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">($);</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"></</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">script</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">></span></span></code></pre></div></div></div><hr><h2 id="_2-quick-start-examples" tabindex="-1">2. Quick Start Examples <a class="header-anchor" href="#_2-quick-start-examples" aria-label="Permalink to "2. Quick Start Examples""></a></h2><p>SigPro uses <strong>PascalCase</strong> for Tag Helpers (e.g., <code>Div</code>, <code>Button</code>) to provide a clean, component-like syntax without needing JSX.</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-qFD4a" id="tab-oqu1DS4" checked><label data-title="Mainstream (Bundlers)" for="tab-oqu1DS4">Mainstream (Bundlers)</label><input type="radio" name="group-qFD4a" id="tab-jgbfsrv"><label data-title="Classic (Direct CDN)" for="tab-jgbfsrv">Classic (Direct CDN)</label></div><div class="blocks"><div class="language-javascript vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">javascript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// File: App.js</span></span>
|
||||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"></</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">script</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">></span></span></code></pre></div></div></div><hr><h2 id="_2-quick-start-examples" tabindex="-1">2. Quick Start Examples <a class="header-anchor" href="#_2-quick-start-examples" aria-label="Permalink to "2. Quick Start Examples""></a></h2><p>SigPro uses <strong>PascalCase</strong> for Tag Helpers (e.g., <code>Div</code>, <code>Button</code>) to provide a clean, component-like syntax without needing JSX.</p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-GOQ8D" id="tab-5wdz_6z" checked><label data-title="Mainstream (Bundlers)" for="tab-5wdz_6z">Mainstream (Bundlers)</label><input type="radio" name="group-GOQ8D" id="tab-uTYcfih"><label data-title="Classic (Direct CDN)" for="tab-uTYcfih">Classic (Direct CDN)</label></div><div class="blocks"><div class="language-javascript vp-adaptive-theme active"><button title="Copy Code" class="copy"></button><span class="lang">javascript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// File: App.js</span></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { $ } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 'sigpro'</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">; </span></span>
|
||||
<span class="line"></span>
|
||||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> App</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
||||
@@ -1 +1 @@
|
||||
{"api_html.md":"DSCIaSlE","api_mount.md":"CoM2SFqU","api_quick.md":"Dw-DUc7L","api_router.md":"Cn98LjXO","api_signal.md":"BmorvARW","api_tags.md":"BKWIb8mV","api_watch.md":"BEM6Qssx","index.md":"By6smViD","install.md":"HK-a2_Fb","ui_quick.md":"CsppjR8J","vite_plugin.md":"CTs8LDIL"}
|
||||
{"api_for.md":"CGMDz0Px","api_html.md":"DSCIaSlE","api_if.md":"C-36XjK0","api_mount.md":"CoM2SFqU","api_quick.md":"D3C2EJww","api_router.md":"Cn98LjXO","api_signal.md":"BmorvARW","api_tags.md":"BKWIb8mV","api_watch.md":"BEM6Qssx","index.md":"By6smViD","install.md":"C1tyiPaQ","ui_quick.md":"CsppjR8J","vite_plugin.md":"CTs8LDIL"}
|
||||
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -42,9 +42,11 @@ export default defineConfig({
|
||||
{ text: 'Quick Start', link: '/api/quick' },
|
||||
{ text: '$', link: '/api/signal' },
|
||||
{ text: '$.watch', link: '/api/watch' },
|
||||
{ text: '$.html', link: '/api/html' },
|
||||
{ text: '$.if', link: '/api/if' },
|
||||
{ text: '$.for', link: '/api/for' },
|
||||
{ text: '$.router', link: '/api/router' },
|
||||
{ text: '$.mount', link: '/api/mount' },
|
||||
{ text: '$.html', link: '/api/html' },
|
||||
{ text: 'Tags', link: '/api/tags' },
|
||||
]
|
||||
},
|
||||
|
||||
83
src/docs/api/for.md
Normal file
83
src/docs/api/for.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# ♻️ Reactive Lists: `$.for( )`
|
||||
|
||||
The `$.for` function is a high-performance list renderer. It maps an array (or a Signal containing an array) to DOM nodes. Unlike a simple `.map()`, `$.for` is **keyed**, meaning it only updates, moves, or deletes the specific items that changed.
|
||||
|
||||
## 🛠️ Function Signature
|
||||
|
||||
```typescript
|
||||
$.for(
|
||||
source: Signal<any[]> | Function | any[],
|
||||
render: (item: any, index: number) => HTMLElement,
|
||||
keyFn: (item: any, index: number) => string | number
|
||||
): HTMLElement
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **`source`** | `Signal` | Yes | The reactive array to iterate over. |
|
||||
| **`render`** | `Function` | Yes | A function that returns a component or Node for each item. |
|
||||
| **`keyFn`** | `Function` | Yes | A function to extract a **unique ID** for each item (crucial for performance). |
|
||||
|
||||
**Returns:** A `div` element with `display: contents` containing the live list.
|
||||
|
||||
---
|
||||
|
||||
## 📖 Usage Patterns
|
||||
|
||||
### 1. Basic Keyed List
|
||||
Always use a unique property (like an `id`) as a key to ensure SigPro doesn't recreate nodes unnecessarily.
|
||||
|
||||
```javascript
|
||||
const users = $([
|
||||
{ id: 1, name: "Alice" },
|
||||
{ id: 2, name: "Bob" }
|
||||
]);
|
||||
|
||||
Ul({ class: "list" }, [
|
||||
$.for(users,
|
||||
(user) => Li({ class: "p-2" }, user.name),
|
||||
(user) => user.id
|
||||
)
|
||||
]);
|
||||
```
|
||||
|
||||
### 2. Handling Primitive Arrays
|
||||
If your array contains simple strings or numbers, you can use the value itself or the index as a key (though the index is less efficient for reordering).
|
||||
|
||||
```javascript
|
||||
const tags = $(["Tech", "JS", "Web"]);
|
||||
|
||||
Div({ class: "flex gap-1" }, [
|
||||
$.for(tags, (tag) => Badge(tag), (tag) => tag)
|
||||
]);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ How it Works (The Reconciliation)
|
||||
|
||||
When the `source` signal changes, `$.for` performs the following steps:
|
||||
|
||||
1. **Key Diffing**: It compares the new keys with the previous ones stored in an internal `Map`.
|
||||
2. **Node Reuse**: If a key already exists, the DOM node is **reused** and moved to its new position. No new elements are created.
|
||||
3. **Cleanup**: If a key disappears from the list, SigPro calls `.destroy()` on that specific item's instance. This stops all its internal watchers and removes its DOM nodes.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 💡 Performance Tips
|
||||
|
||||
* **Stable Keys**: Never use `Math.random()` as a key. This will force SigPro to destroy and recreate the entire list on every update, killing performance.
|
||||
* **Component Encapsulation**: If each item in your list has its own complex internal state, `$.for` ensures that state is preserved even if the list is reordered, as long as the key remains the same.
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Summary Comparison
|
||||
|
||||
| Feature | Standard `Array.map` | SigPro `$.for` |
|
||||
| :--- | :--- | :--- |
|
||||
| **Re-render** | Re-renders everything | Only updates changes |
|
||||
| **DOM Nodes** | Re-created every time | **Reused via Keys** |
|
||||
| **Memory** | Potential leaks | **Automatic Cleanup** |
|
||||
| **State** | Lost on re-render | **Preserved per item** |
|
||||
88
src/docs/api/if.md
Normal file
88
src/docs/api/if.md
Normal file
@@ -0,0 +1,88 @@
|
||||
|
||||
# 🔀 Reactive Branching: `$.if( )`
|
||||
|
||||
The `$.if` function is a reactive control flow operator. It manages the conditional rendering of components, ensuring that only the active branch exists in the DOM and in memory.
|
||||
|
||||
## 🛠️ Function Signature
|
||||
|
||||
```typescript
|
||||
$.if(
|
||||
condition: Signal<boolean> | Function,
|
||||
thenVal: Component | Node,
|
||||
otherwiseVal?: Component | Node
|
||||
): HTMLElement
|
||||
```
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **`condition`** | `Signal` | Yes | A reactive source that determines which branch to render. |
|
||||
| **`thenVal`** | `any` | Yes | The content to show when the condition is **truthy**. |
|
||||
| **`otherwiseVal`** | `any` | No | The content to show when the condition is **falsy** (defaults to null). |
|
||||
|
||||
**Returns:** A `div` element with `display: contents` that acts as a reactive portal for the branches.
|
||||
|
||||
---
|
||||
|
||||
## 📖 Usage Patterns
|
||||
|
||||
### 1. Simple Toggle
|
||||
The most common use case is showing or hiding a single element based on a state.
|
||||
|
||||
```javascript
|
||||
const isVisible = $(false);
|
||||
|
||||
Div([
|
||||
Button({ onclick: () => isVisible(!isVisible()) }, "Toggle Message"),
|
||||
|
||||
$.if(isVisible,
|
||||
P("Now you see me!"),
|
||||
P("Now you don't...")
|
||||
)
|
||||
]);
|
||||
```
|
||||
|
||||
### 2. Lazy Component Loading
|
||||
Unlike using a hidden class (CSS `display: none`), `$.if` is **lazy**. The branch that isn't active **is never created**. This saves memory and initial processing time.
|
||||
|
||||
```javascript
|
||||
$.if(() => user.isLogged(),
|
||||
() => Dashboard(), // Only executed if logged in
|
||||
() => LoginGate() // Only executed if guest
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧹 Automatic Cleanup
|
||||
|
||||
One of the core strengths of `$.if` is its integrated **Cleanup** logic. SigPro ensures that when a branch is swapped out, it is completely purged.
|
||||
|
||||
1. **Stop Watchers**: All `$.watch` calls inside the inactive branch are permanently stopped.
|
||||
2. **Unbind Events**: Event listeners attached via `$.html` are removed.
|
||||
3. **Recursive Sweep**: SigPro performs a deep "sweep" of the removed branch to ensure no nested reactive effects remain active.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
* **Function Wrappers**: If your branches are heavy (e.g., they contain complex components), wrap them in a function `() => MyComponent()`. This prevents the component from being initialized until the condition actually meets its requirement.
|
||||
* **Logical Expressions**: You can pass a complex computed function as the condition:
|
||||
```javascript
|
||||
$.if(() => count() > 10 && status() === 'ready',
|
||||
Span("Threshold reached!")
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Technical Comparison
|
||||
|
||||
| Feature | Standard CSS `hidden` | SigPro `$.if` |
|
||||
| :--- | :--- | :--- |
|
||||
| **DOM Presence** | Always present | Only if active |
|
||||
| **Reactivity** | Still processing in background | **Paused/Destroyed** |
|
||||
| **Memory usage** | Higher | **Optimized** |
|
||||
| **Cleanup** | Manual | **Automatic** |
|
||||
|
||||
@@ -11,8 +11,8 @@ SigPro is a high-performance micro-framework that updates the **Real DOM** surgi
|
||||
| **`$.watch(fn)`** | `(function) => stopFn` | **Automatic Mode:** Tracks any signal touched inside. Returns a stop function. |
|
||||
| **`$.watch(deps, fn)`** | `(Array, function) => stopFn` | **Explicit Mode:** Only runs when signals in `deps` change. Used for Cleanup. |
|
||||
| **`$.html(tag, props, kids)`** | `(string, obj, any) => Element` | The low-level DOM factory. Attaches `._cleanups` to every element. |
|
||||
| **`$.If(cond, then, else?)`** | `(Signal, fn, fn?) => Node` | Reactive conditional. Automatically destroys the "else" branch memory. |
|
||||
| **`$.For(list, itemFn)`** | `(Signal, fn) => Node` | Optimized list renderer. Manages individual item lifecycles. |
|
||||
| **`$.if(cond, then, else?)`** | `(Signal, fn, fn?) => Node` | Reactive conditional. Automatically destroys the "else" branch memory. |
|
||||
| **`$.for(list, itemFn)`** | `(Signal, fn) => Node` | Optimized list renderer. Manages individual item lifecycles. |
|
||||
| **`$.router(routes)`** | `(Array) => Element` | Hash-based SPA router. Uses Explicit Watch to prevent memory leaks. |
|
||||
| **`$.mount(node, target)`** | `(any, string\|Node) => Runtime` | Entry point. Creates a root instance with `.destroy()` capabilities. |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user