natxocc/sigpro
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
b1ee605e7116cf7c3a62af775876db13bb5a6ef1
sigpro/docs/assets/api_html.md.COPskx0H.js
natxocc 58f6876261 New 1.1.3
2026-03-26 00:39:30 +01:00

25 lines
16 KiB
JavaScript
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import{_ as i,o as t,c as a,ae as e}from"./chunks/framework.C8AWLET_.js";const c=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,p,r,k,o){return t(),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 is the foundation for all Tag Constructors in SigPro.</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:#24292E;--shiki-dark:#E1E4E8;">$.</span><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>Boolean Props</strong>: Uses <code>toggleAttribute</code> (e.g., <code>checked</code>, <code>disabled</code>, <code>hidden</code>).</li><li><strong>Class Names</strong>: Supports <code>class</code> or <code>className</code> interchangeably.</li></ul><h3 id="_2-event-listeners-modifiers" tabindex="-1">2. Event Listeners &amp; Modifiers <a class="header-anchor" href="#_2-event-listeners-modifiers" aria-label="Permalink to &quot;2. Event Listeners &amp; Modifiers&quot;">​</a></h3><p>Events are defined by the <code>on</code> prefix. SigPro supports <strong>Dot Notation</strong> for common event operations:</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;">html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;button&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // e.preventDefault() is called automatically</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;onsubmit.prevent&quot;</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:#6F42C1;--shiki-dark:#B392F0;"> save</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>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // e.stopPropagation() is called automatically</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;onclick.stop&quot;</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;No bubbling&quot;</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;"> // { once: true } listener option</span></span>
<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;onclick.once&quot;</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;Runs only once&quot;</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:#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" tabindex="-1">3. Reactive Attributes <a class="header-anchor" href="#_3-reactive-attributes" aria-label="Permalink to &quot;3. Reactive Attributes&quot;">​</a></h3><p>If an attribute value is a <strong>function</strong> (like a Signal), <code>$.html</code> creates an internal <code>$.effect</code> 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:#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;div&quot;</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-reactive-children" tabindex="-1">4. Reactive Children <a class="header-anchor" href="#_4-reactive-children" aria-label="Permalink to &quot;4. Reactive Children&quot;">​</a></h3><p>Children can be static or dynamic. When a child is a function, SigPro creates a reactive boundary 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:#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;div&quot;</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="🔄-two-way-binding-operator" tabindex="-1">🔄 Two-Way Binding Operator (<code>$</code>) <a class="header-anchor" href="#🔄-two-way-binding-operator" aria-label="Permalink to &quot;🔄 Two-Way Binding Operator (\`$\`)&quot;">​</a></h2><p>When a property starts with <code>$</code>, <code>$.html</code> enables bidirectional synchronization. This is primarily used for form inputs.</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;">html</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;input&quot;</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;">// Syncs input value &lt;-&gt; signal</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h2 id="🧹-automatic-cleanup" tabindex="-1">🧹 Automatic Cleanup <a class="header-anchor" href="#🧹-automatic-cleanup" aria-label="Permalink to &quot;🧹 Automatic Cleanup&quot;">​</a></h2><p>Every element created with <code>$.html</code> gets a hidden <code>._cleanups</code> property (a <code>Set</code>).</p><ul><li>When SigPro removes an element via <code>$.view</code> or <code>$.router</code>, it automatically executes all functions stored in this Set (stopping effects, removing listeners, etc.).</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:</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:#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;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>`,30)])])}const E=i(n,[["render",l]]);export{c as __pageData,E as default};
Reference in New Issue View Git Blame Copy Permalink