ivue 1.0.2 → 1.0.3

package/docs/docs/components/examples/{Counter.vue → CounterBasic.vue}

@@ -2,16 +2,16 @@
 import { ref } from 'vue';
 import { ivue } from 'ivue';
 
-class ToDo {
+class Counter {
   count = ref(0) as unknown as number;
   increment() {
     this.count++;
   }
 }
 
-const todo = ivue(ToDo);
+const counter = ivue(Counter);
 </script>
 <template>
-  <a href="javascript:void" @click="() => todo.increment()">Increment</a>
-  Count: {{ todo.count }}
+  <a href="javascript:void(0)" @click="() => counter.increment()">Increment</a>
+  Count: {{ counter.count }}
 </template>

package/docs/docs/components/examples/CounterComposables.vue

@@ -0,0 +1,20 @@
+<script lang="ts" setup>
+import { ref } from 'vue';
+import { ivue, UnwrapComposable } from 'ivue';
+import { useMouse } from '@vueuse/core';
+
+class Counter {
+  count = ref(0) as unknown as number;
+  increment() {
+    this.count++;
+  }
+  mouse = useMouse() as unknown as UnwrapComposable<typeof useMouse>
+}
+
+const counter = ivue(Counter);
+</script>
+<template>
+  <a href="javascript:void(0)" @click="() => counter.increment()">Increment</a>
+  Count: {{ counter.count }} <br />
+  Mouse: X: {{ counter.mouse.x }}, Y: {{ counter.mouse.y }}
+</template>

package/docs/docs/components/examples/CounterComposablesDestructuring.vue

@@ -0,0 +1,66 @@
+<script lang="ts" setup>
+import { computed, ref } from 'vue';
+import { ivue, type UnwrapComposable } from 'ivue';
+import { useMouse as _useMouse } from '@vueuse/core';
+
+function useMouse() {
+  const { x, y } = _useMouse();
+  const _sum = ref(0);
+
+  function sum() {
+    _sum.value = x.value + y.value;
+  }
+
+  const total = computed(() => {
+    return _sum;
+  });
+
+  return {
+    x,
+    y,
+    sum,
+    total,
+  };
+}
+
+/**
+ * Use the Utility Type: UnwrapComposable<typeof YourComposableFunctionName>
+ * to get he resulting unwrapped composable properties and functions.
+ */
+type UseMouse = UnwrapComposable<typeof useMouse>;
+
+class Counter {
+  count = ref(0) as unknown as number;
+
+  increment() {
+    this.count++;
+  }
+
+  // x, y are properties that will be destructured into this class
+  x!: UseMouse['x']; // Unwrapped Ref<number> becomes -> number
+  y!: UseMouse['y']; // Unwrapped Ref<number> becomes -> number
+  
+  sum!: UseMouse['sum']; // 'sum' method that will be destructured into this class on construct()
+  total!: UseMouse['total'];  // 'total' method that will be destructured into this class on construct()
+
+  constructor() {
+    ({
+      x: this.x,
+      y: this.y,
+      sum: this.sum,
+      total: this.total
+    } = useMouse() as unknown as UseMouse);
+  }
+}
+
+const counter = ivue(Counter);
+</script>
+<template>
+  <a href="javascript:void(0)" @click="() => counter.increment()">Increment</a>
+  Count: {{ counter.count }} <br />
+  Mouse: X: {{ counter.x }}, Y: {{ counter.y }} 
+  <br />
+  Total (computed): {{ counter.total }}
+  <br />
+  <button class="button" @click="() => counter.sum()">Click This Big Sum Button To Total X + Y</button>
+</template>

package/docs/docs/components/examples/CounterDefineExpose.vue

@@ -0,0 +1,12 @@
+<script lang="ts" setup>
+import { ivue } from 'ivue';
+
+import Counter from './CounterDefineExposeClass'
+
+const counter = ivue(Counter);
+
+defineExpose<Counter>(counter);
+</script>
+<template>
+  Count: {{ counter.count }}
+</template>

package/docs/docs/components/examples/CounterDefineExposeClass.ts

@@ -0,0 +1,11 @@
+import { ref } from 'vue';
+
+export default class Counter {
+  count = ref(0) as unknown as number;
+  increment() {
+    this.count++;
+  }
+  decrement() {
+    this.count--;
+  }
+}

package/docs/docs/components/examples/CounterExternalRefs.vue

@@ -0,0 +1,25 @@
+<script lang="ts" setup>
+import { ref } from 'vue';
+import { ivue } from 'ivue';
+
+type SpanRef = HTMLElement | null;
+
+class Counter {
+  constructor(public span: SpanRef) {}
+  count = ref(0) as unknown as number;
+  increment() {
+    this.count++;
+    (this.span as HTMLElement).innerHTML = String(this.count + 1);
+  }
+}
+
+const span = ref<SpanRef>();
+const counter = ivue(Counter, span as unknown as SpanRef);
+
+defineExpose<Counter>(counter);
+</script>
+<template>
+  <a href="javascript:void(0)" @click="() => counter.increment()">Increment</a>
+  Count: {{ counter.count }} 
+  <span ref="span"></span>
+</template>

package/docs/docs/components/examples/CounterInternalRefs.vue

@@ -0,0 +1,26 @@
+<script lang="ts" setup>
+import { ref } from 'vue';
+import { ivue } from 'ivue';
+
+class Counter {
+  count = ref(0) as unknown as number;
+  span = ref(null) as unknown as HTMLElement | null;
+  increment() {
+    this.count++;
+    (this.span as HTMLElement).innerHTML = String(this.count + 1);
+  }
+}
+
+const counter = ivue(Counter);
+const { span } = counter.toRefs(['span']);
+/**
+ * Or you can use `const { span } = counter.toRefs();`
+ * but `const { span } = counter.toRefs(['span']);` is more performant
+ * because we are only looping through 1 property instead of all of them.
+ */ 
+</script>
+<template>
+  <a href="javascript:void(0)" @click="() => counter.increment()">Increment</a>
+  Count: {{ counter.count }}
+  <span ref="span"></span>
+</template>

package/docs/docs/components/examples/CounterWithProps.vue

@@ -0,0 +1,29 @@
+<script lang="ts" setup>
+import { ref } from 'vue';
+import { ivue } from 'ivue';
+
+interface CounterProps {
+  initialCount: number;
+}
+const props = defineProps<CounterProps>();
+
+class Counter {
+  constructor(public props: CounterProps) {
+    this.count = this.props.initialCount;
+  }
+  count = ref(0) as unknown as number;
+  increment() {
+    this.count++;
+  }
+}
+
+/**
+ * NOTICE that: ivue(ClassName, ...args) uses TypeScript to infer 
+ * the correct argument types that you need to pass to the constructor.
+ */
+const counter = ivue(Counter, props);
+</script>
+<template>
+  <a href="javascript:void(0)" @click="() => counter.increment()">Increment</a>
+  Count: {{ counter.count }}
+</template>

package/docs/docs/components/examples/CounterWithPropsAndEmits.vue

@@ -0,0 +1,36 @@
+<script lang="ts" setup>
+import { ref } from 'vue';
+import { ivue } from 'ivue';
+
+interface CounterProps {
+  initialCount: number;
+}
+
+interface CounterEmits {
+  (e: 'increment', count: number): void;
+}
+
+const props = defineProps<CounterProps>();
+const emit = defineEmits<CounterEmits>();
+
+class Counter {
+  constructor(public props: CounterProps, public emit: CounterEmits) {
+    this.count = this.props.initialCount;
+  }
+  count = ref(0) as unknown as number;
+  increment() {
+    this.count++;
+    this.emit('increment', this.count);
+  }
+}
+
+/**
+ * NOTICE that: ivue(ClassName, ...args) uses TypeScript to infer 
+ * the correct argument types that you need to pass to the constructor.
+ */
+const counter = ivue(Counter, props, emit);
+</script>
+<template>
+  <a href="javascript:void(0)" @click="() => counter.increment()">Increment</a>
+  Count: {{ counter.count }}
+</template>

package/docs/docs/index.md

@@ -12,11 +12,11 @@ import Button from './components/Button.vue'
 ## Features
 <div style="padding-left:20px;">
 &ndash; Simple & Elegant Architecture<br />
-&ndash; Extendible Classes aligned with TypeScript Class design<br />
-&ndash; Extendible Props Defaults<br />
-&ndash; Extendible Emits<br />
-&ndash; Extendible Slots<br />
-&ndash; Extendible Components<br />
+&ndash; Extensible Classes aligned with TypeScript Class design<br />
+&ndash; Extensible Props Defaults<br />
+&ndash; Extensible Emits<br />
+&ndash; Extensible Slots<br />
+&ndash; Extensible Components<br />
 &ndash; Improves DX by elegantly dealing with .value in the background<br />
 &ndash; Can be used both as a Store and a View Model for Components<br />
 &ndash; Provides Full TypeScript Support<br />

package/docs/docs/pages/getting-started.md

@@ -1,14 +1,18 @@
-# Installation
+# Getting Started
 
-In your terminal install ivue:
+## Install
+
+The only dependency for `ivue` is Vue 3, so it is easy to get started.
+
+In your terminal install `ivue` using:
 ```bash
-# via yarn
+# yarn
 yarn add ivue
 
-# via npm
+# npm
 npm i ivue
 
-# via pnpm
+# pnpm
 pnpm i ivue
 ```
 

package/docs/docs/pages/introduction.md

@@ -1,6 +1,9 @@
+<script setup lang="ts">
+import Button from '../components/Button.vue'
+</script>
 # What is Infinite Vue (ivue) ?
 
-## The Purpose of Infinite Vue
+## The Problem `ivue` Aims to Solve
 
 With the development of React hooks and Vue following in its footsteps with introduction of Vue 3 Composition API, the ecosystem has moved away from Options API. 
 
@@ -12,34 +15,39 @@ See: https://vuejs.org/guide/extras/reactivity-transform.html
 
 
 ::: info IVUE UNIFIES COMPOSITION & OPTIONS API VIA CLASS BASED ARCHITECTURE
-&mdash;&nbsp; ivue mitigates the downsides of both Composition API and Options API, uses only their strengths and brings back Object Oriented Programming to allow the development of complex and scallable apps.
+&mdash;&nbsp; `ivue` mitigates the downsides of both Composition API and Options API, uses only their strengths and brings back Object Oriented Programming to allow the development of complex and scallable apps.
 
-&mdash;&nbsp; ivue is fully interoperable with Composition API and does not work against it but rather with it, so you can use all of ecosystems composables seamlessly.
+&mdash;&nbsp; `ivue` is fully interoperable with Composition API and does not work against it but rather with it, so you can use all of ecosystems composables seamlessly.
 
-&mdash;&nbsp; ivue also offers a set of functions and utility types to make extensible & exportable props defaults, extensible emits and extensible slots possible.
+&mdash;&nbsp; `ivue` also offers a set of functions and utility types to make extensible & exportable props defaults, extensible emits and extensible slots possible.
 :::
 
 ## Classes are Back with Full Vue 3 Compatibility & Beyond
 
-With failed implementations of classes in React and also failed implementations using class components in Vue 2 / 3, the ecosystem decided that classes are bad and moved to pure procedural designs, while procedural programming has its strength, it also comes with its own weaknesses, like lack of inheritance and true composition.
+With failed implementations of classes in React and also failed implementations using class components in Vue 2 / 3, the ecosystem decided that classes are bad and moved to pure procedural designs. 
+
+While procedural programming has its strength, it also comes with its own weaknesses, like lack of inheritance and true composition.
 
 ::: info IVUE IS DIFFERENT
-&mdash; &nbsp;ivue does NOT inherit from a base class<br />
-&mdash; &nbsp;ivue does NOT use decorators to achieve its objectives<br />
-&mdash; &nbsp;ivue does NOT alter Vue 3 underlying behavior<br />
-&mdash; &nbsp;ivue is NOT class components (though you can build components with it)<br />
+&mdash; &nbsp;`ivue` does NOT inherit from a base class<br />
+&mdash; &nbsp;`ivue` does NOT use decorators to achieve its objectives<br />
+&mdash; &nbsp;`ivue` does NOT alter Vue 3 underlying behavior<br />
+&mdash; &nbsp;`ivue` is NOT the same as class components (though you can build components with it)<br />
 :::
 
 ## Infinite Vue Achitecture
 
-ivue mimicks native JavaScript / TypeScript class implementation by extending descriptors up the whole prototype chain thus supporting classical inheritance.
+`ivue` mimicks native JavaScript / TypeScript class implementation by extending descriptors (getters and setters) up the whole prototype chain thus supporting classical inheritance.
 
 By using TypeScript we are able to infer the arguments of the main `ivue` initializer function and pass the arguments to the constructor.
 
 `ivue` initializer function returns a reactive object with getters converted to computeds and adds `.toRefs()` method to the object, `.toRefs()` allows the object to be converted to native composable structure, so it can interoperate as a composable if needed.
 
+`ivue` aims to be opaque and minimal, just doing the minimum to convert a class to a reactive object, leaving the rest to be implemented using Vue 3 composition api inside an initializer function called `.init()` 
+
+You can read more about `ivue` internal architecture in <Button href="/pages/how-it-works" label="How it works?" /> page.
 
 ## When to use Infinite Vue?
 
-When complexity of your app or components becomes very high using **ivue** can become a natural choice to deal with that complexity. Because there is no `.value` in ivue, everything is simply a reactive object of unwrapped Refs.
+When complexity of your app or components becomes very high using `ivue` can become a natural choice to deal with that complexity. Because `.value` is abstracted away in `ivue`, everything is simply a reactive object of unwrapped Refs.
 

package/docs/docs/pages/usage.md

@@ -1,16 +1,225 @@
+<style>
+  .button { 
+    padding: 5px 10px; 
+    border-color: var(--vp-custom-block-details-border);
+    color: var(--vp-custom-block-details-text);
+    background-color: var(--vp-custom-block-details-bg);
+    border-radius: 5px;  
+    margin-bottom: 2px;
+    transition: 0.5s;
+  }
+  .button:hover { 
+    opacity: 0.8;
+  }
+  .button:active { 
+    opacity:0.9;
+  }
+</style>
 <script lang="ts" setup>
-import { createContentLoader } from 'vitepress'
-import Counter from '../components/examples/Counter.vue'
+import { ref } from 'vue';
 
+import CounterBasic from '../components/examples/CounterBasic.vue'
+import CounterWithProps from '../components/examples/CounterWithProps.vue'
+import CounterWithPropsAndEmits from '../components/examples/CounterWithPropsAndEmits.vue'
+import CounterDefineExpose from '../components/examples/CounterDefineExpose.vue'
+import CounterDefineExposeClass from '../components/examples/CounterDefineExposeClass'
+import CounterExternalRefs from '../components/examples/CounterExternalRefs.vue'
+import CounterInternalRefs from '../components/examples/CounterInternalRefs.vue'
+import CounterComposables from '../components/examples/CounterComposables.vue'
+import CounterComposablesDestructuring from '../components/examples/CounterComposablesDestructuring.vue'
+
+// <For CounterWithPropsAndEmits example start>
+function onIncrement(value: number) {
+  alert('Count is now: ' + value);
+}
+// </For CounterWithPropsAndEmits example end>
+
+// <For CounterDefineExpose example start>
+const defineExposeRef = ref<CounterDefineExposeClass | null>(null);
+
+function increment() {
+  defineExposeRef.value.increment();
+}
+
+function decrement() {
+  defineExposeRef.value.decrement();
+}
+// </For CounterDefineExpose example end>
+
+</script>
+
+# Example Usage
+
+Using ivue is very simple, but you need to understand a few principles. See the examples below expanding on each principle.
+
+## Basic Usage
+
+Classic Counter example built with `ivue`
+::: code-group
+<<< @/components/examples/CounterBasic.vue{15 vue:line-numbers}
+:::
+:::details For this example we initialize the component like this:
+<template>
+<CounterBasic />
+</template>
+:::
+
+### Result:
+
+<CounterBasic />
+::: warning NOTICE: JavaScript Class Caveat
+ See `() => counter.increment()`. You cannot simply use `counter.increment` to refer to the method when it was defined as a object of a class, because that method would not know that it has to be bound to `counter`. You have to either use `() => counter.increment()` or `counter.increment.bind(counter)`, but the latter example is too verbose, so the preferred more readable way is to use an arrow function.
+:::
+
+## Using Props
+
+See the highlighted sections related to props.
+::: code-group
+<<< @/components/examples/CounterWithProps.vue{5-8,15-16,24 vue:line-numbers}
+:::
+:::details For this example we initialize the component like this:
+<template>
+<CounterWithProps :initial-count="5" />
+</template>
+:::
+
+### Result:
+
+<CounterWithProps :initial-count="5" />
+
+## Using Emits
+
+See the highlighted sections related to `defineExpose`
+
+::: code-group
+<<< @/components/examples/CounterWithPropsAndEmits.vue{9-11,14,20,22,31 vue:line-numbers}
+:::
+:::details For this example we initialize the component like this:
+
+```vue
+<script setup lang="ts">
+function onIncrement(value: number) {
+  alert('Count is now: ' + value);
+}
+</script>
+<template>
+  <CounterWithPropsAndEmits :initial-count="5" @increment="onIncrement" />
+</template>
+```
+
+:::
+
+### Result:
+
+<CounterWithPropsAndEmits :initial-count="5" @increment="onIncrement" />
+
+## Using Refs
+
+### Refs Defined Outside of ivue
+
+::: code-group
+<<< @/components/examples/CounterExternalRefs.vue{vue:line-numbers}
+:::
+:::details For this example we initialize the component like this:
+
+```vue
+<template>
+  <CounterExternalRefs />
+</template>
+```
+
+:::
+
+### Result:
+
+<CounterExternalRefs />
+
+### Refs Defined Inside of ivue class
+
+::: code-group
+<<< @/components/examples/CounterInternalRefs.vue{vue:line-numbers}
+:::
+:::details For this example we initialize the component like this:
+
+```vue
+<template>
+  <CounterInternalRefs />
+</template>
+```
+
+:::
+
+### Result:
+
+<CounterInternalRefs />
+
+## Using Define Expose
+
+See the highlighted sections related to `defineExpose`.
+::: code-group
+<<< @/components/examples/CounterDefineExpose.vue{8 vue:line-numbers}
+<<< @/components/examples/CounterDefineExposeClass.ts{ts:line-numbers}
+:::
+:::details For this example we initialize the component like this:
+```vue
+<script setup lang="ts">
+const defineExposeRef = ref<CounterDefineExposeClass | null>(null);
+
+function increment() {
+  defineExposeRef.value.increment();
+}
+
+function decrement() {
+  defineExposeRef.value.decrement();
+}
 </script>
+<template>
+  <button @click="increment">
+    Increment via Component Ref from Parent Component</button
+  ><br />
+  <button @click="decrement">
+    Decrement via Component Ref from Parent Component
+  </button>
+  <CounterDefineExpose />
+</template>
+```
+:::
+
+### Result:
+
+<button class="button" @click="increment">Increment via Component Ref from Parent Component</button><br />
+<button class="button" @click="decrement">Decrement via Component Ref from Parent Component</button>
+<CounterDefineExpose ref="defineExposeRef" />
 
-# Basic Usage
+## Using Composables
 
-Classic Counter example built with `ivue`:
+See the highlighted sections related to composable usage.
+::: code-group
+<<< @/components/examples/CounterComposables.vue{4,11,19 vue:line-numbers}
+:::
+:::details For this example we initialize the component like this:
+```vue
+<template>
+  <CounterComposables />
+</template>
+```
+:::
+
+### Result:
+<CounterComposables />
 
-<<< @/components/examples/Counter.vue{vue}
-```ts
-{{counterContent}}
+### Destructuring composable into the class
+See the highlighted sections related to destructuring composable usage.
+::: code-group
+<<< @/components/examples/CounterComposablesDestructuring.vue{4,11,19 vue:line-numbers}
+:::
+:::details For this example we initialize the component like this:
+```vue
+<template>
+  <CounterComposablesDestructuring />
+</template>
 ```
-Result:
-<Counter />
+:::
+
+### Result:
+<CounterComposablesDestructuring />

package/docs/package.json

@@ -18,13 +18,14 @@
     "eslint-plugin-import": "^2.29.1",
     "eslint-plugin-vue": "^9.14.1",
     "execa": "^8.0.0",
-    "ivue": "^1.0.0",
+    "ivue": "^1.0.2",
     "typescript": "^4.5.4",
     "vite-plugin-dynamic-import": "^1.5.0",
     "vite-tsconfig-paths": "^4.3.2",
     "vitepress": "^1.0.0",
     "vue": "3.2.44",
-    "vue-dd": "1.6.7"
+    "vue-dd": "1.6.7",
+    "vue-use": "^0.2.0"
   },
   "pnpm": {
     "peerDependencyRules": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ivue",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Infinite Vue – Class Based Architecture for Vue 3",
   "type": "module",
   "exports": {