New 1.1.3

2026-03-26 00:39:30 +01:00
parent 5d799608a3
commit 58f6876261
121 changed files with 3038 additions and 4707 deletions
--- a/docs/assets/api_signal.md.BmorvARW.js
+++ b/docs/assets/api_signal.md.BmorvARW.js
@@ -0,0 +1,14 @@
+import{_ as i,o as a,c as t,ae as e}from"./chunks/framework.C8AWLET_.js";const g=JSON.parse('{"title":"💎 The Signal Function: $( )","description":"","frontmatter":{},"headers":[],"relativePath":"api/signal.md","filePath":"api/signal.md"}'),n={name:"api/signal.md"};function l(h,s,p,k,r,d){return a(),t("div",null,[...s[0]||(s[0]=[e(`<h1 id="💎-the-signal-function" tabindex="-1">💎 The Signal Function: <code>$( )</code> <a class="header-anchor" href="#💎-the-signal-function" aria-label="Permalink to &quot;💎 The Signal Function: \`$( )\`&quot;"></a></h1><p>The <code>$( )</code> function is the core constructor of SigPro. It defines how data is stored, computed, and persisted.</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;">$</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(initialValue: any, key</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">?:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> string): Signal</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">$</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(computation: Function): ComputedSignal</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>initialValue</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 starting value of your signal.</td></tr><tr><td style="text-align:left;"><strong><code>computation</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 value based on other signals.</td></tr><tr><td style="text-align:left;"><strong><code>key</code></strong></td><td style="text-align:left;"><code>string</code></td><td style="text-align:left;">No</td><td style="text-align:left;">A unique name to persist the signal in <code>localStorage</code>.</td></tr></tbody></table><p><em>*Either an initial value or a computation function must be provided.</em></p><hr><h2 id="📖-usage-patterns" tabindex="-1">📖 Usage Patterns <a class="header-anchor" href="#📖-usage-patterns" aria-label="Permalink to &quot;📖 Usage Patterns&quot;"></a></h2><h3 id="_1-simple-state" tabindex="-1">1. Simple State <a class="header-anchor" href="#_1-simple-state" aria-label="Permalink to &quot;1. Simple State&quot;"></a></h3><p><strong><code>$(value)</code></strong> Creates a writable signal. It returns a function that acts as both <strong>getter</strong> and <strong>setter</strong>.</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;"> count</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;">0</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;">count</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();    </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Read (0)</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">count</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">10</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);  </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Write (10)</span></span></code></pre></div><h3 id="_2-persistent-state" tabindex="-1">2. Persistent State <a class="header-anchor" href="#_2-persistent-state" aria-label="Permalink to &quot;2. Persistent State&quot;"></a></h3><p><strong><code>$(value, key)</code></strong> Creates a writable signal that syncs with the browser&#39;s storage.</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;"> theme</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;">&quot;light&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;app-theme&quot;</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;">theme</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;dark&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">); </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Automatically calls localStorage.setItem(&quot;app-theme&quot;, &#39;&quot;dark&quot;&#39;)</span></span></code></pre></div><p><em>Note: On page load, SigPro will prioritize the value found in <code>localStorage</code> over the <code>initialValue</code>.</em></p><h3 id="_3-computed-state-derived" tabindex="-1">3. Computed State (Derived) <a class="header-anchor" href="#_3-computed-state-derived" aria-label="Permalink to &quot;3. Computed State (Derived)&quot;"></a></h3><p><strong><code>$(function)</code></strong> Creates a read-only signal that updates automatically when any signal used inside it changes.</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;"> price</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;">100</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> tax</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;">0.21</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;">// This tracks both &#39;price&#39; and &#39;tax&#39; automatically</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> total</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:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> price</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 style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> +</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> tax</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">()));</span></span></code></pre></div><hr><h2 id="🔄-updating-with-logic" tabindex="-1">🔄 Updating with Logic <a class="header-anchor" href="#🔄-updating-with-logic" aria-label="Permalink to &quot;🔄 Updating with Logic&quot;"></a></h2><p>When calling the setter, you can pass an <strong>updater function</strong> to access the current value safely.</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;"> list</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;">&quot;A&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;B&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;">// Adds &quot;C&quot; using the previous state</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">list</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">prev</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =&gt;</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;">prev, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;C&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">]);</span></span></code></pre></div>`,22)])])}const c=i(n,[["render",l]]);export{g as __pageData,c as default};