cradova 2.2.2 → 2.3.0

package/README.md

@@ -49,11 +49,12 @@ Cradova follows the [VJS specification](https://github.com/fridaycandour/cradova
 
 Cradova is aimed to be fast and simple with and fewer abstractions and yet easily composable.
 
-Cradova does't rely on visual DOM or diff algorithms to manage the DOM, instead, State management is done more elegantly with a simple predictive model, manually and easily with all the speed.
+Cradova is not built on visual DOM or diff algorithms.
+Instead, State management is done more elegantly with a simple predictive model, simple and easy with all the speed.
 
-### is this a big benefit?
+## Is this a big benefit?
 
-Undoubtedly, this provides a significant advantage. You can experience it firsthand and decide for yourself.
+Undoubtedly, this provides a significant advantage. You can experience it firsthand and decide.
 
 Cradova has already been utilized in multiple production projects, and we will continuously update this page to showcase our advancements as we keep improving.
 
@@ -83,12 +84,10 @@ npm i cradova
 
 Many aspects of Cradova are not reflected in the following example. More functionality will be entailed in future docs.
 
-Here's an example of create a basic component in Cradova:
+## A basic component in Cradova:
 
 ```js
-// cradova v2.0.0 comes with all html tags prebuilt and fully typed
-// this gives your app more performance gain.
-import _, { h1 } from "cradova";
+import { div, h1 } from "cradova";
 
 function Hello(name) {
   return h1("Hello " + name, {
@@ -99,88 +98,56 @@ function Hello(name) {
   });
 }
 
-// document fragment empty cradova call _()
-
-const html = _(Hello("peter"), Hello("joe"));
+const html = div(Hello("peter"), Hello("joe"));
 
 document.body.append(html);
 ```
 
-```js
-// regular example
-import _ from "cradova";
-
-function Hello(name) {
-  return _("h1", "Hello " + name);
-}
-
-const html = _(Hello("peter"), Hello("joe"));
-
-document.body.append(html);
-```
+## working with state:
 
-## Using Screen
+this a collection of basic examples
+you can choose any that best suite what problem you want to solve
 
 ```js
-import _, { Screen, Router } from "cradova";
+import _, {
+  button,
+  createSignal,
+  Ref,
+  reference,
+  h1,
+  br,
+  div,
+} from "../dist/index.js";
 
-function HelloMessage(name) {
-  // an effect run once after screen renders
-  this.effect(() => {
-   const name = new Promise((res) => {
-      res("friday");
-    });
-    this.updateState(await name)
+function Hello(name) {
+  return h1("Hello " + name, {
+    className: "title",
+    style: {
+      color: "grey",
+    },
   });
-  // effects can be used to make api calls needed for the page
-  return _("div", "Hello  " + name);
 }
 
+const html = div(Hello("peter"), Hello("joe"));
+
+// reference (not state)
+
+function typingExample() {
+  const re = new reference();
+  return _(
+    "div",
+    input({
+      oninput() {
+        re.text.innerText = this.value;
+      },
+      placeholder: "typing simulation",
+    }),
+    p(" no thing typed yet!", { reference: re.bindAs("text") })
+  );
+}
 
-/*
-
-when using router and screens
-
-cradova will create a div with data-cra-id=cradova-app-wrapper
-
-if it already exist cradova will use it instead
-
-so if you want to use your own mount point then create a div with data-cra-id="cradova-app-wrapper"
-
-*/
-
-const home = new Screen({
-  name: "hello page", // page title
-  template: HelloMessage,
-  ...
-});
-
-Router.route("/", home);
-
-// navigates to that page
-// Router.navigate("/home", data, force);
-// get the page ready in the background
-// Router.packageScreen("/home");
-// get route params for this page
-// Router.getParams();
-
-```
-
-## State management
-
-```js
-
-
- // element can have this.updateState when the shouldUpdate props is true
-
-// Ref components
-
-// state can be managed from a store when using createSignal or simpleStores
-// this method is not yet documented
-
-import _, { Ref } from "cradova";
-
-// simple count
+// setting shouldUpdate to true
+// gives you this.updateState binding
 
 function counter() {
   let num = 0;
@@ -193,32 +160,42 @@ function counter() {
   });
 }
 
+// Another example with data- attribute
+
 function dataCounter() {
   return _("h1| 0", {
     shouldUpdate: true,
     "data-num": "0",
     onclick() {
-     const num = Number(this.getAttribute("data-num")) + 1;
-      this.updateState({ text: num, $num: num });
+      const num = this.getAttribute("data-num") * 1 + 1;
+      this.updateState({ text: num, "data-num": num });
     },
   });
 }
 
-function HelloMessage(name = "no name") {
-  return _("div.foo#bar", {
+// hello message
+
+function HelloMessage() {
+  return div({
     shouldUpdate: true,
-    text: "hello  " + name,
+    text: "Click to get a greeting",
     onclick() {
       const name = prompt("what are your names");
-      this.updateState({ text: "hello " + name });
+      this.updateState({
+        text: name ? "hello " + name : "Click to get a greeting",
+      });
     },
   });
 }
 
-const nameRef = new Ref(function ( name ) {
+// using cradova Ref
+
+const nameRef = new Ref(function (name) {
   const self = this;
   return _("div.foo#bar", {
-    text: "hello" + (name || "no name"),
+    text: name
+      ? "hello " + (name || " user 2")
+      : "Click to get a second greeting",
     onclick() {
       const name = prompt();
       self.updateState(name);
@@ -226,62 +203,251 @@ const nameRef = new Ref(function ( name ) {
   });
 });
 
-/*
-cradova Ref are component objects
-with methods for rendering, pre-rendering, and updating a it dom elements.
+function App() {
+  return div(counter, dataCounter, HelloMessage, br, nameRef);
+}
 
-Ref also has the feature to stash input values need by the components
+// add your app to the DOM
 
-*/
+document.body.append(App());
+```
+
+## Simple Todo list
+
+Let's see a simple TodoList example
+
+```js
+import _, {
+  button,
+  createSignal,
+  css,
+  div,
+  input,
+  main,
+  p,
+  Ref,
+  reference,
+} from "../dist/index.js";
+
+function TodoList() {
+  // can be used to hold multiple references
+  const referenceSet = new reference();
+
+  // creating a store
+  const todoStore = new createSignal([
+    "take bath",
+    "code code code",
+    "take a break",
+  ]);
+
+  // create actions
+  todoStore.createAction("add-todo", function (todo) {
+    this.set([...this.value, todo]);
+  });
 
+  todoStore.createAction("remove-todo", function (todo) {
+    const ind = this.value.indexOf(todo);
+    this.value.splice(ind, 1);
+    this.set(this.value);
+  });
 
-function Home() {
-  return _("div.foo#bar",
-   counter,
-   dataCounter,
-   HelloMessage,
-   nameRef.render( "no name" )
+  // bind Ref to Signal
+  todoStore.bindRef(todoList);
+
+  // markup
+  return main(
+    _`|Todo List`,
+    div(
+      input({
+        placeholder: "type in todo",
+        reference: referenceSet.bindAs("todoInput"),
+      }),
+      button("Add todo", {
+        onclick() {
+          todoStore.fireAction("add-todo", referenceSet.todoInput.value);
+          referenceSet.todoInput.value = "";
+        },
+      })
+    ),
+    todoList.render
   );
 }
 
+const todoList = new Ref(function () {
+  const self = this;
+  return div(
+    self.Signal.value.map((item) =>
+      p(item, {
+        title: "click to remove",
+        onclick() {
+          self.Signal.fireAction("remove-todo", item);
+        },
+      })
+    )
+  );
+});
+
+document.body.appendChild(TodoList());
+
+css`
+  body {
+    box-sizing: border-box;
+    display: flex;
+  }
+  main {
+    margin: auto;
+  }
+  main > p {
+    font-size: 2rem;
+  }
+`;
+```
+
+## working with screen and Router:
+
+unlike just appending stuff to the DOM,
+a better to build apps is to use a routing system.
+
+Cradova Router is a module that allows you do the following:
+
+Create specified routes in you application
+help you orchestrate navigation
+render a screen on a route
+pre-render a screen in the background if you want to.
+listen to Navigation changes
+create error boundary at screen level.
+persist rendered screens by default
+allow parallel screen rendering for every unique route scheme
+
+let's try an example.
+
+```js
+import _, { Screen, Router } from "cradova";
+
+// Ref can be used as screens
+
+const template = new Ref(function (name) {
+  // an effect run once after screen renders
+  const self = this;
+  self.effect(() => {
+    const name = new Promise((res) => {
+      res("john doe");
+    });
+    setTimeout(async () => {
+      self.updateState(await name);
+    }, 1000);
+  });
+  // effects can be used to make api calls needed for the page
+  return _("div", name ? ">>>>>>>>  Hello  " + name : "  loading...");
+});
+
 const home = new Screen({
   name: "home page", // page title
-  template: Home,
-  ...
+  template,
+});
+
+// in your routes.ts file
+Router.BrowserRoutes({
+  "/home": home,
+  "/lazy-loaded-home": async () => await import("./home"),
 });
+// creates these routes
 
-/*
+Router.packageScreen("/home", data);
+// get the page ready in the background
+
+Router.navigate("/home", data);
+// navigates to that page
 
-Nice things about cradova screens
+Router.getParams();
+// get route params for this current page
+
+Router.onPageEvent((lastRoute, newRoute) => {
+  console.log(lastRoute, newRoute);
+});
+// listen for navigation changes
+```
+
+### More info
+
+---
+
+More info on cradova Router
+
+---
+
+Every cradova app mounts on a div with attribute data-wrapper="app"
+
+if it already exist cradova will use it instead.
+
+cradova will create a div with data-wrapper="app" if it doesn't exists already.
+
+so if you want to use your own mount point then create a div with data-wrapper="app".
+
+---
+
+More info on cradova screens
+
+---
 
 screens are rendered once by default to hack
 responsiveness making your app work fast as user navigates.
 
 this behavior can be override
 by passing
-prerender: false
+persist: false
 in the constructor
 
-
 Cradova screens has
 onActivate() and
-onDeactivate() methods
+onDeactivate() methods which is also available in the
+component function on the this variable bound to it.
 
-these allow you manage rendering
-circle for each in your app
+this allow you manage rendering
+circle for each screen in your app
 
-*/
+---
 
-Router.route("/", home);
-```
+More info on cradova Ref
+
+---
+
+Refs are dynamic components, they have simple abstractions like:
+
+- Effects
+- stash
+- preRender
+- updateState
+
+these behaviors allow you manage rendering
+circle for refs in your app
+
+---
+
+More info on cradova createSignal
+
+---
+
+Cradova Signals allows you to create powerful data stores.
+
+with ability to:
+
+- create store
+- create actions and fire them
+- bind a Ref
+- listen to changes
+- persist changes to localStorage
+- update a cradova Ref and bindings automatically
+
+With these simple and easy abstractions, you can use datastores with powerful convenience.
 
 ## Documentation
 
-At the moment, we're in the process of creating documentation for Cradova, and we have limited resources. If you're interested in lending a hand, we invite you to join our community, gain firsthand experience, and contribute to the advancement of Cradova.
+At the moment, we're in the process of creating a documentation website for Cradova, and we have limited resources. If you're interested in lending a hand, we invite you to join our community, gain firsthand experience, and contribute to the advancement of Cradova.
 
 ## Getting Help
 
-To get further insights and help on Cradova, visit our new [Telegram Community Chat](https://t.me/cradovaframework).
+To get further insights and help on Cradova, visit our [Discord](https://discord.gg/b7fvMg38) and [Telegram](https://t.me/cradovaframework) Community Chats.
 
 ## Contributing