cradova 2.2.3 → 2.3.1

package/README.md

@@ -49,15 +49,16 @@ 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.
 
-[current version changes](https://github.com/fridaycandour/cradova/blob/main/CHANGELOG.md#v220)
+[current version changes](https://github.com/fridaycandour/cradova/blob/main/CHANGELOG.md#v230)
 
 ## Installation
 
@@ -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,21 @@ 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";
-
-function HelloMessage(name) {
-  // an effect run once after screen renders
-  this.effect(() => {
-   const name = new Promise((res) => {
-      res("friday");
-    });
-    this.updateState(await name)
-  });
-  // effects can be used to make api calls needed for the page
-  return _("div", "Hello  " + name);
-}
-
-
-/*
-
-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
+import _, { button, createSignal, Ref, reference, h1, br, div } from "cradova";
 
-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 +125,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 +168,267 @@ const nameRef = new Ref(function ( name ) {
   });
 });
 
-/*
-cradova Ref are component objects
-with methods for rendering, pre-rendering, and updating a it dom elements.
+// 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") })
+  );
+}
 
-Ref also has the feature to stash input values need by the components
+function App() {
+  return div(counter, dataCounter, HelloMessage, br, nameRef);
+}
+
+// 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 "cradova";
+
+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
+
+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
 
-Nice things about 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
 

package/dist/index.d.ts

@@ -11,9 +11,9 @@ declare module "cradova" {
           beforeMount?: () => void;
           afterMount?: () => void;
           text?: string;
+          reference?: any;
           stateID?: string;
           shouldUpdate?: boolean;
-          assert?: any;
         }
     )[]
   ) => T;
@@ -80,10 +80,6 @@ declare module "cradova" {
     persist?: boolean;
   };
 
-  export const makeElement: (
-    element: Record<string, any>,
-    ...ElementChildrenAndPropertyList: ElementType<HTMLElement>[]
-  ) => Record<string, any>;
   export const a: ElementType<HTMLAnchorElement>;
   export const abbr: ElementType<HTMLElement>;
   export const address: ElementType<HTMLElement>;
@@ -150,7 +146,6 @@ declare module "cradova" {
   export const meta: ElementType<HTMLMetaElement>;
   export const meter: ElementType<HTMLMeterElement>;
   export const nav: ElementType<HTMLElement>;
-  export const noscript: ElementType<HTMLElement>;
   export const object: ElementType<HTMLObjectElement>;
   export const ol: ElementType<HTMLOListElement>;
   export const optgroup: ElementType<HTMLOptGroupElement>;
@@ -222,32 +217,16 @@ declare module "cradova" {
   ): Promise<unknown>;
 
   /**
-   * Cradova afterMount event
+   * Cradova event
    */
-  export let cradovaAftermountEvent: CustomEvent<unknown>;
-  /**
-Write CSS styles in Javascript
-@example
-
-css("#container",
-{
-    height: "100%",
-    height: "100%",
-    background-color: "#ff9800"
-})
-
-css(".btn:hover",
-{
-    height: "100%",
-    height: "100%",
-    background-color: "#ff9800"
-})
-
-*/
-  export function css(
-    identifier: string,
-    properties?: Record<string, string>
-  ): void;
+  export class cradovaEvent {
+    private listeners;
+    addEventListener(eventName: string, callback: any): void;
+    removeEventListener(eventName: string, callback: any): void;
+    dispatchEvent(eventName: string, eventArgs?: any): void;
+  }
+  export const CradovaEvent: cradovaEvent;
+  export function css(identifier: string | TemplateStringsArray): void;
   /**
    *
    * @param {expression} condition
@@ -271,13 +250,14 @@ css(".btn:hover",
   type RefProps<D> = D | any;
   export class Ref<D> {
     private component;
-    private stateID;
     private effects;
     private effectuate;
     private rendered;
     private published;
     private hasFirstStateUpdateRun;
     private preRendered;
+    private reference;
+    Signal: createSignal<any> | undefined;
     stash: D | undefined;
     constructor(component: (data?: RefProps<D>) => any);
     preRender(data?: RefProps<D>): void;
@@ -290,7 +270,8 @@ css(".btn:hover",
      * @returns () => HTMLElement
      */
     render(data?: D, stash?: boolean): HTMLElement;
-    instance(): any;
+    instance(): Record<string, any>;
+    _setExtra(Extra: createSignal<any>): void;
     /**
      * Cradova Ref
      * ---
@@ -324,6 +305,12 @@ css(".btn:hover",
     constructor(cb: () => Promise<any>);
     load(): Promise<void>;
   }
+  export class reference {
+    [x: string]: Record<string, any>;
+    bindAs(name: string): any;
+    _appendDom(name: string, Element: any): void;
+    _appendDomForce(name: string, Element: any): void;
+  }
 
   /**
    *  Cradova Signal
@@ -391,11 +378,11 @@ css(".btn:hover",
      * @param key - string key of the action
      * @param data - data for the action
      */
-    fireAction(key: string, data?: Type): void;
+    fireAction(key: string, data?: unknown): void;
     /**
      * Cradova
      * ---
-     * is used to bind store data to an element
+     * is used to bind store data to any element
      *
      * @param prop
      * @returns something
@@ -412,7 +399,7 @@ css(".btn:hover",
      */
     bindRef(
       ref: any,
-      binding: {
+      binding?: {
         event?: string;
         signalProperty: string;
         _element_property: string;
@@ -458,13 +445,75 @@ css(".btn:hover",
     state?: stateType
   ): any;
 
-  /**
-   * Cradova Router
+  /** cradova router
    * ---
-   * Facilitates navigation within the application and initializes
-   * page views based on the matched routes.
+   * Registers a route.
+   *
+   * @param {string}   path     Route path.
+   * @param {any} screen the cradova document tree for the route.
    */
-  export const Router: Record<string, any>;
+  class RouterClass {
+    /** cradova router
+     * ---
+     * Registers a route.
+     *
+     * accepts an object containing
+     *
+     * @param {string}   path     Route path.
+     * @param {any} screen the cradova screen.
+     */
+    BrowserRoutes(obj: Record<string, any>): void;
+    /**
+     * Cradova Router
+     * ------
+     *
+     * Navigates to a designated screen in your app
+     *
+     * @param href string
+     * @param data object
+     * @param force boolean
+     */
+    navigate(
+      href: string,
+      data?: Record<string, any> | null,
+      force?: boolean
+    ): void;
+    /** cradova router
+     * ---
+     * Listen for navigation events
+     *
+     * @param callback   () => void
+     */
+    onPageEvent(callback: () => void): void;
+    /** cradova router
+     * ---
+     * get a screen ready before time.
+     *
+     * @param {string}   path Route path.
+     * @param {any} data data for the screen.
+     */
+    packageScreen(path: string, data?: any): Promise<void>;
+    /**
+     * Cradova Router
+     * ------
+     *
+     * return last set router params
+     *
+     * .
+     */
+    getParams: () => any;
+    /**
+     * Cradova
+     * ---
+     * Error Handler for your app
+     *
+     * @param callback
+     * @param path? page path
+     */
+    addErrorHandler(callback: () => void): void;
+    _mount(): void;
+  }
+  export const Router: RouterClass;
 
   /**
    *  Cradova Screen