ivue 1.2.0 → 1.2.2

package/docs/docs/.vitepress/dist/assets/{pages_guidelines.md.Dkyp5V72.js → pages_guidelines.md.BI1PexCc.lean.js}

@@ -1,4 +1,4 @@
-import{w as c,A as E,M as g}from"./chunks/index.es.BJUrCfJB.js";import{d as h,s as y,o as p,c as k,j as a,k as l,a as u,t as F,F as b,y as f,I as m,a5 as r}from"./chunks/framework.CvEKxEoK.js";const D=a("br",null,null,-1),A=h({__name:"CounterExternalRefsDetailed",setup(d,{expose:n}){class e{constructor(s){this.span=s,this.count=g(0)}init(){f(()=>{this.span.innerHTML="Initial span text!"})}increment(){this.count++,this.span.innerHTML=String(this.count+1)}}const t=y(null),i=c(e,E(t));return n(i),(o,s)=>(p(),k(b,null,[a("a",{href:"javascript:void(0)",onClick:s[0]||(s[0]=()=>l(i).increment())},"Increment"),u(" Count: "+F(l(i).count)+" ",1),D,a("span",{ref_key:"span",ref:t},null,512)],64))}}),C=r(`<h1 id="guidelines" tabindex="-1">Guidelines <a class="header-anchor" href="#guidelines" aria-label="Permalink to &quot;Guidelines&quot;">​</a></h1><h2 id="dos-and-don-ts" tabindex="-1">Dos and Don&#39;ts <a class="header-anchor" href="#dos-and-don-ts" aria-label="Permalink to &quot;Dos and Don&#39;ts&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</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;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> UseMouse</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> UseComposable</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">typeof</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> useMouse&gt;;</span></span>
+import{E as c,x as E,S as g}from"./chunks/index.es.CUL6WvM-.js";import{d as h,s as y,o as p,c as k,j as a,k as l,a as u,t as F,F as b,y as f,I as m,a5 as r}from"./chunks/framework.CvEKxEoK.js";const D=a("br",null,null,-1),A=h({__name:"CounterExternalRefsDetailed",setup(d,{expose:n}){class e{constructor(s){this.span=s,this.count=g(0)}init(){f(()=>{this.span.innerHTML="Initial span text!"})}increment(){this.count++,this.span.innerHTML=String(this.count+1)}}const t=y(null),i=c(e,E(t));return n(i),(o,s)=>(p(),k(b,null,[a("a",{href:"javascript:void(0)",onClick:s[0]||(s[0]=()=>l(i).increment())},"Increment"),u(" Count: "+F(l(i).count)+" ",1),D,a("span",{ref_key:"span",ref:t},null,512)],64))}}),C=r(`<h1 id="guidelines" tabindex="-1">Guidelines <a class="header-anchor" href="#guidelines" aria-label="Permalink to &quot;Guidelines&quot;">​</a></h1><h2 id="dos-and-don-ts" tabindex="-1">Dos and Don&#39;ts <a class="header-anchor" href="#dos-and-don-ts" aria-label="Permalink to &quot;Dos and Don&#39;ts&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</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;">type</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> UseMouse</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> UseComposable</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&lt;</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">typeof</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> useMouse&gt;;</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">/**</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> * Example of a properly defined ivue class.</span></span>
 <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> */</span></span>
@@ -67,7 +67,7 @@ import{w as c,A as E,M as g}from"./chunks/index.es.BJUrCfJB.js";import{d as h,s
 <span class="line"><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;">/** ✓ Properly intilized IVUE class runner. */</span></span>
-<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> counter</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ivue</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(Counter, props, emit);</span></span></code></pre></div><h3 id="use-ref-for-properties" tabindex="-1">Use ref() for properties <a class="header-anchor" href="#use-ref-for-properties" aria-label="Permalink to &quot;Use ref() for properties&quot;">​</a></h3><p><code>ivue</code> recommends all class properties to be defined as <code>ref()</code> to be able to interoperate with <code>defineExpose()</code>, if you simply pass reactive props which are not Refs through <code>defineExpose()</code>, they will lose reactivity. <code>ref()</code> refs just like computed refs get flattened into the <code>reactive()</code> object, so there is no need to worry about using <code>.value</code>. The <code>ref()</code> refs are necessary just internally for Vue 3 to know which refs to keep reactive.</p><h3 id="unwrap-de-ref-the-types" tabindex="-1">Unwrap (de-Ref) the types <a class="header-anchor" href="#unwrap-de-ref-the-types" aria-label="Permalink to &quot;Unwrap (de-Ref) the types&quot;">​</a></h3><p>Next, we convert the types back to their normal types as if they have no reactivity at all, so <code>Ref&lt;number&gt;</code> is <code>number</code> in <code>ivue</code>, so rather than going in the direction of complexifying the types, we are going in the opposite direction towards simplification.</p><h3 id="use-standard-declaration-syntax-for-functions" tabindex="-1">Use standard declaration syntax for functions <a class="header-anchor" href="#use-standard-declaration-syntax-for-functions" aria-label="Permalink to &quot;Use standard declaration syntax for functions&quot;">​</a></h3><p><code>ivue</code> recommends all class functions to be defined in plain full function style (not arrow functions), this allows all <code>ivue</code> classes to be extensible at any point. By using plain standard functions, it allows the developer to be able to override them at any time by simply extending the class.</p><h3 id="do-not-use-arrow-functions-in-class-declarations" tabindex="-1">Do not use arrow functions in class declarations <a class="header-anchor" href="#do-not-use-arrow-functions-in-class-declarations" aria-label="Permalink to &quot;Do not use arrow functions in class declarations&quot;">​</a></h3><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>Arrow functions break full extensibility of classes because they carry their own context at the point of declaration, so avoid using them inside of <code>ivue</code> classes.</p></div><h2 id="constructor-vs-init" tabindex="-1">constructor() vs .init() <a class="header-anchor" href="#constructor-vs-init" aria-label="Permalink to &quot;constructor() vs .init()&quot;">​</a></h2><h4 id="use-constructor-to-assign-properties-of-the-class-and-cast-refs-to-unwrapped-bare-types" tabindex="-1">Use <code>constructor()</code> to assign properties of the class and cast Refs to Unwrapped bare types. <br> <a class="header-anchor" href="#use-constructor-to-assign-properties-of-the-class-and-cast-refs-to-unwrapped-bare-types" aria-label="Permalink to &quot;Use \`constructor()\` to assign properties of the class and cast Refs to Unwrapped bare types. &lt;br /&gt;&quot;">​</a></h4><h4 id="use-init-to-declare-reactive-state-functions-like-watch-watcheffect-and-lifecycle-hooks-like-onmounted-onbeforemount-etc-do-assignments-of-reactive-properties-since-init-already-has-access-to-reactive-state-through-this" tabindex="-1">Use <code>.init()</code> to declare reactive state functions like <code>watch</code>, <code>watchEffect</code>, and lifecycle hooks like <code>onMounted</code>, <code>onBeforeMount</code> etc, do assignments of reactive properties, since <code>.init()</code> already has access to <code>reactive()</code> state through <code>this</code>.<br> <a class="header-anchor" href="#use-init-to-declare-reactive-state-functions-like-watch-watcheffect-and-lifecycle-hooks-like-onmounted-onbeforemount-etc-do-assignments-of-reactive-properties-since-init-already-has-access-to-reactive-state-through-this" aria-label="Permalink to &quot;Use \`.init()\` to declare reactive state functions like \`watch\`, \`watchEffect\`, and lifecycle hooks like \`onMounted\`, \`onBeforeMount\` etc, do assignments of reactive properties, since \`.init()\` already has access to \`reactive()\` state through \`this\`.&lt;br /&gt;&quot;">​</a></h4><hr><p>Inside the <code>constructor()</code> method you still have access to non-reactive state, because when <code>constructor()</code> is initialized, it does NOT yet have access to the reactive properties of the class, since it was not yet converted to <code>reactive()</code> by <code>ivue</code>, so if you use the properties like Refs or ComputedRefs inside <code>constructor()</code> you would have to use them with the <code>.value</code>.</p><p>As a general rule, there is no need to manipulate the values in the <code>constructor()</code>, use constructor only for assigning the properties and casting the types of those assigned properties to the unwrapped (de-Refed) final state of the resulting <code>reactive()</code> object.</p><p><strong>Let&#39;s look at a <code>constructor()</code> vs <code>.init()</code> example:</strong></p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-Tiorj" id="tab-m7tdUXd" checked><label for="tab-m7tdUXd">CounterExternalRefsDetailed.vue</label></div><div class="blocks"><div class="language-vue vp-adaptive-theme active line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">vue</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;">&lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">script</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> setup</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> lang</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> counter</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ivue</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(Counter, props, emit);</span></span></code></pre></div><h3 id="use-ref-for-properties" tabindex="-1">Use ref() for properties <a class="header-anchor" href="#use-ref-for-properties" aria-label="Permalink to &quot;Use ref() for properties&quot;">​</a></h3><p><code>ivue</code> recommends all class properties to be defined as <code>ref()</code> to be able to interoperate with <code>defineExpose()</code>, if you simply pass reactive props which are not Refs through <code>defineExpose()</code>, they will lose reactivity. <code>ref()</code> refs just like computed refs get flattened into the <code>reactive()</code> object, so there is no need to worry about using <code>.value</code>. The <code>ref()</code> refs are necessary just internally for Vue 3 to know which refs to keep reactive.</p><h3 id="unwrap-de-ref-the-types" tabindex="-1">Unwrap (de-Ref) the types <a class="header-anchor" href="#unwrap-de-ref-the-types" aria-label="Permalink to &quot;Unwrap (de-Ref) the types&quot;">​</a></h3><p>Next, we convert the types back to their normal types as if they have no reactivity at all, so <code>Ref&lt;number&gt;</code> is <code>number</code> in <code>ivue</code>, so rather than going in the direction of complexifying the types, we are going in the opposite direction towards simplification.</p><h3 id="use-standard-declaration-syntax-for-functions" tabindex="-1">Use standard declaration syntax for functions <a class="header-anchor" href="#use-standard-declaration-syntax-for-functions" aria-label="Permalink to &quot;Use standard declaration syntax for functions&quot;">​</a></h3><p><code>ivue</code> recommends all class functions to be defined in plain full function style (not arrow functions), this allows all <code>ivue</code> classes to be extensible at any point. By using plain standard functions, it allows the developer to be able to override them at any time by simply extending the class.</p><h3 id="do-not-use-arrow-functions-in-class-declarations" tabindex="-1">Do not use arrow functions in class declarations <a class="header-anchor" href="#do-not-use-arrow-functions-in-class-declarations" aria-label="Permalink to &quot;Do not use arrow functions in class declarations&quot;">​</a></h3><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>Arrow functions break full extensibility of classes because they carry their own context at the point of declaration, so avoid using them inside of <code>ivue</code> classes.</p></div><h2 id="constructor-vs-init" tabindex="-1">constructor() vs .init() <a class="header-anchor" href="#constructor-vs-init" aria-label="Permalink to &quot;constructor() vs .init()&quot;">​</a></h2><h4 id="use-constructor-to-assign-properties-of-the-class-and-cast-refs-to-unwrapped-bare-types" tabindex="-1">Use <code>constructor()</code> to assign properties of the class and cast Refs to Unwrapped bare types. <br> <a class="header-anchor" href="#use-constructor-to-assign-properties-of-the-class-and-cast-refs-to-unwrapped-bare-types" aria-label="Permalink to &quot;Use \`constructor()\` to assign properties of the class and cast Refs to Unwrapped bare types. &lt;br /&gt;&quot;">​</a></h4><h4 id="use-init-to-declare-reactive-state-functions-like-watch-watcheffect-and-lifecycle-hooks-like-onmounted-onbeforemount-etc-do-assignments-of-reactive-properties-since-init-already-has-access-to-reactive-state-through-this" tabindex="-1">Use <code>.init()</code> to declare reactive state functions like <code>watch</code>, <code>watchEffect</code>, and lifecycle hooks like <code>onMounted</code>, <code>onBeforeMount</code> etc, do assignments of reactive properties, since <code>.init()</code> already has access to <code>reactive()</code> state through <code>this</code>.<br> <a class="header-anchor" href="#use-init-to-declare-reactive-state-functions-like-watch-watcheffect-and-lifecycle-hooks-like-onmounted-onbeforemount-etc-do-assignments-of-reactive-properties-since-init-already-has-access-to-reactive-state-through-this" aria-label="Permalink to &quot;Use \`.init()\` to declare reactive state functions like \`watch\`, \`watchEffect\`, and lifecycle hooks like \`onMounted\`, \`onBeforeMount\` etc, do assignments of reactive properties, since \`.init()\` already has access to \`reactive()\` state through \`this\`.&lt;br /&gt;&quot;">​</a></h4><hr><p>Inside the <code>constructor()</code> method you still have access to non-reactive state, because when <code>constructor()</code> is initialized, it does NOT yet have access to the reactive properties of the class, since it was not yet converted to <code>reactive()</code> by <code>ivue</code>, so if you use the properties like Refs or ComputedRefs inside <code>constructor()</code> you would have to use them with the <code>.value</code>.</p><p>As a general rule, there is no need to manipulate the values in the <code>constructor()</code>, use constructor only for assigning the properties and casting the types of those assigned properties to the unwrapped (de-Refed) final state of the resulting <code>reactive()</code> object.</p><p><strong>Let&#39;s look at a <code>constructor()</code> vs <code>.init()</code> example:</strong></p><div class="vp-code-group vp-adaptive-theme"><div class="tabs"><input type="radio" name="group-jtXx9" id="tab-2MPQNLR" checked><label for="tab-2MPQNLR">CounterExternalRefsDetailed.vue</label></div><div class="blocks"><div class="language-vue vp-adaptive-theme active line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">vue</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;">&lt;</span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">script</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> setup</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> lang</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;ts&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">&gt;</span></span>
 <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { onMounted, ref } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;vue&#39;</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;"> { ivue, iref, iuse } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;ivue&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
 <span class="line"></span>