Update new version

docs/assets/api_html.md.QmhwKd7f.js

@@ -0,0 +1,18 @@
+import{_ as t,o as i,c as a,ae as e}from"./chunks/framework.C8AWLET_.js";const k=JSON.parse('{"title":"🏗️ The DOM Factory: $html( )","description":"","frontmatter":{},"headers":[],"relativePath":"api/html.md","filePath":"api/html.md"}'),n={name:"api/html.md"};function l(h,s,r,o,p,d){return i(),a("div",null,[...s[0]||(s[0]=[e(`<h1 id="🏗️-the-dom-factory-html" tabindex="-1">🏗️ The DOM Factory: <code>$html( )</code> <a class="header-anchor" href="#🏗️-the-dom-factory-html" aria-label="Permalink to &quot;🏗️ The DOM Factory: \`$html( )\`&quot;">​</a></h1><p><code>$html</code> is the internal engine that creates, attributes, and attaches reactivity to DOM elements. It uses <code>$.watch</code> to maintain a live, high-performance link between your Signals and the Document Object Model.</p><h2 id="🛠-function-signature" tabindex="-1">🛠 Function Signature <a class="header-anchor" href="#🛠-function-signature" aria-label="Permalink to &quot;🛠 Function Signature&quot;">​</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:#6F42C1;--shiki-dark:#B392F0;">$html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(tagName: string, props</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Object, children</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:#24292E;--shiki-dark:#E1E4E8;"> any): 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>tagName</code></strong></td><td style="text-align:left;"><code>string</code></td><td style="text-align:left;">Yes</td><td style="text-align:left;">Valid HTML tag name (e.g., <code>&quot;div&quot;</code>, <code>&quot;button&quot;</code>).</td></tr><tr><td style="text-align:left;"><strong><code>props</code></strong></td><td style="text-align:left;"><code>Object</code></td><td style="text-align:left;">No</td><td style="text-align:left;">HTML attributes, event listeners, and reactive bindings.</td></tr><tr><td style="text-align:left;"><strong><code>children</code></strong></td><td style="text-align:left;"><code>any</code></td><td style="text-align:left;">No</td><td style="text-align:left;">Nested elements, text strings, or reactive functions.</td></tr></tbody></table><hr><h2 id="📖-key-features" tabindex="-1">📖 Key Features <a class="header-anchor" href="#📖-key-features" aria-label="Permalink to &quot;📖 Key Features&quot;">​</a></h2><h3 id="_1-attribute-handling" tabindex="-1">1. Attribute Handling <a class="header-anchor" href="#_1-attribute-handling" aria-label="Permalink to &quot;1. Attribute Handling&quot;">​</a></h3><p>SigPro intelligently decides how to apply each property:</p><ul><li><strong>Standard Props</strong>: Applied via <code>setAttribute</code> or direct property assignment.</li><li><strong>Class Names</strong>: Supports <code>class</code> or <code>className</code> interchangeably.</li><li><strong>Boolean Props</strong>: Automatic handling for <code>checked</code>, <code>disabled</code>, <code>hidden</code>, etc.</li></ul><h3 id="_2-event-listeners" tabindex="-1">2. Event Listeners <a class="header-anchor" href="#_2-event-listeners" aria-label="Permalink to &quot;2. Event Listeners&quot;">​</a></h3><p>Events are defined by the <code>on</code> prefix. SigPro automatically registers the listener and ensures it is cleaned up when the element is destroyed.</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:#6F42C1;--shiki-dark:#B392F0;">Button</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  onclick</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">e</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> console.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">log</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Clicked!&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, e),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Click Me&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><h3 id="_3-reactive-attributes-one-way" tabindex="-1">3. Reactive Attributes (One-Way) <a class="header-anchor" href="#_3-reactive-attributes-one-way" aria-label="Permalink to &quot;3. Reactive Attributes (One-Way)&quot;">​</a></h3><p>If an attribute value is a <strong>function</strong> (like a Signal), <code>$html</code> creates an internal <strong><code>$.watch</code></strong> to keep the DOM in sync with the 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:#6F42C1;--shiki-dark:#B392F0;">Div</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // Updates the class whenever &#39;theme()&#39; changes</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">  class</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> theme</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;"> &quot;dark&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bg-black&quot;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> :</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;bg-white&quot;</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h3 id="_4-smart-two-way-binding-automatic" tabindex="-1">4. Smart Two-Way Binding (Automatic) <a class="header-anchor" href="#_4-smart-two-way-binding-automatic" aria-label="Permalink to &quot;4. Smart Two-Way Binding (Automatic)&quot;">​</a></h3><p>SigPro automatically enables <strong>bidirectional synchronization</strong> when it detects a <strong>Signal</strong> assigned to a form-capable attribute (<code>value</code> or <code>checked</code>) on an input element (<code>input</code>, <code>textarea</code>, <code>select</code>).</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:#6A737D;--shiki-dark:#6A737D;">// Syncs input value &lt;-&gt; signal automatically</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Input</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ </span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  type: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;text&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  value: username </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// No special symbols needed!</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span></code></pre></div><blockquote><p><strong>Note:</strong> To use a Signal as <strong>read-only</strong> in an input, wrap it in an anonymous function: <code>value: () =&gt; username()</code>.</p></blockquote><h3 id="_5-reactive-children" tabindex="-1">5. Reactive Children <a class="header-anchor" href="#_5-reactive-children" aria-label="Permalink to &quot;5. Reactive Children&quot;">​</a></h3><p>Children can be static or dynamic. When a child is a function, SigPro creates a reactive boundary using <code>$.watch</code> for that specific part of the DOM.</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:#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;">  H1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Static Title&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">),</span></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // Only this text node re-renders when &#39;count&#39; changes</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  () </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> \`Current count: \${</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">count</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">()</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span></code></pre></div><hr><h2 id="🧹-memory-management-internal" tabindex="-1">🧹 Memory Management (Internal) <a class="header-anchor" href="#🧹-memory-management-internal" aria-label="Permalink to &quot;🧹 Memory Management (Internal)&quot;">​</a></h2><p>Every element created with <code>$html</code> is &quot;self-aware&quot; regarding its reactive dependencies.</p><ul><li><strong><code>._cleanups</code></strong>: A hidden <code>Set</code> attached to the element that stores all <code>stop()</code> functions from its internal <code>$.watch</code> calls and event listeners.</li><li><strong>Lifecycle</strong>: When an element is removed by a Controller (<code>$.if</code>, <code>$.for</code>, or <code>$.router</code>), SigPro performs a recursive <strong>&quot;sweep&quot;</strong> to execute these cleanups, ensuring <strong>zero memory leaks</strong>.</li></ul><hr><h2 id="💡-tag-constructors-the-shortcuts" tabindex="-1">💡 Tag Constructors (The Shortcuts) <a class="header-anchor" href="#💡-tag-constructors-the-shortcuts" aria-label="Permalink to &quot;💡 Tag Constructors (The Shortcuts)&quot;">​</a></h2><p>Instead of writing <code>$html(&quot;div&quot;, ...)</code> every time, SigPro provides PascalCase global functions for all standard HTML tags:</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:#6A737D;--shiki-dark:#6A737D;">// This:</span></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;">&quot;wrapper&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, [ </span><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;">&quot;Hello&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) ])</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Is exactly equivalent to:</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">$html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;div&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { class: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;wrapper&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, [ </span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">$html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;span&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {}, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Hello&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) ])</span></span></code></pre></div>`,31)])])}const g=t(n,[["render",l]]);export{k as __pageData,g as default};