cradova 3.0.0 → 3.1.1

package/README.md

@@ -41,11 +41,7 @@
 
 Cradova is a web development framework for building Single Page Applications and PWAs.
 
-It's a fast, simple and modern, with powerful state management and routing system.
-
-```
-No matter how complex your UI, cradova helps you build fast, reactivity and scalable web apps.
-```
+It's a fast and simple framework, it provides an easy to use state management and router system.
 
 Cradova follows the [VJS specification](https://github.com/fridaycandour/cradova/blob/main/spec.md)
 
@@ -58,7 +54,7 @@ Instead, State management is done more elegantly with a simple predictive model,
 
 ## Is this a big benefit?
 
-Undoubtedly, this provides a significant advantage. You can experience it firsthand and decide.
+Undoubtedly, this provides a significant advantage.
 
 Cradova has already been utilized in multiple production projects, and we will continuously update this page to showcase our advancements as we keep improving.
 
@@ -115,8 +111,14 @@ you can choose any that best suite what problem you want to solve
 ```js
 import _, { button, createSignal, Ref, reference, h1, br, div } from "cradova";
 
-// setting shouldUpdate to true
-// gives you this.updateState binding
+
+const count = new Ref(function () {
+  const [count, setCounter] = useState(0, this);
+  setTimeout(() => {
+    setCounter(count + 1);
+  }, 1000);
+  return h1(" the current count is = " + count);
+});
 
 function counter() {
   let num = 0;
@@ -185,7 +187,7 @@ function typingExample() {
 }
 
 function App() {
-  return div(counter, dataCounter, HelloMessage, br, nameRef);
+  return div(count, counter, dataCounter, HelloMessage, br, nameRef);
 }
 
 // add your app to the DOM

package/dist/index.d.ts

@@ -1,3 +1,20 @@
+/*
+============================================================================="
+    ██████╗   ██████╗    █████═╗   ███████╗    ███████╗    ██╗   ██╗  █████╗   
+   ██╔════╝   ██╔══██╗  ██╔═╗██║   █      ██  ██╔═════╝█   ██║   ██║  ██╔═╗██  
+   ██║        ██████╔╝  ███████║   █      ██  ██║     ██   ██║   ██║  ██████╗  
+   ██║        ██╔══██╗  ██║  ██║   █      ██  ██║     ██   ╚██╗ ██╔╝  ██║  ██╗ 
+   ╚██████╗   ██║  ██║  ██║  ██║   ███████╔╝   ████████      ╚███╔╝   ██║  ██║ 
+    ╚═════╝   ╚═╝  ╚═╝  ╚═╝  ╚═╝   ╚══════╝     ╚════╝        ╚══╝    ╚═╝  ╚═╝ 
+=============================================================================
+Cradova FrameWork
+@version  3.0.0
+License: Apache V2
+Copyright 2022 Friday Candour. 
+Repository - https://github.com/fridaycandour/cradova
+=============================================================================
+*/
+
 declare module "cradova" {
   /**
    *  Cradova Signal
@@ -69,7 +86,7 @@ declare module "cradova" {
      * @param key - string key of the action
      * @param data - data for the action
      */
-    fireAction(key: string, data?: unknown): void;
+    fireAction(key: string, data?: Type): Type;
     /**
      * Cradova
      * ---
@@ -89,7 +106,7 @@ declare module "cradova" {
      * @param path a property in the object to send to attached ref
      */
     bindRef(
-      ref: Partial<Ref<unknown>>, //! there's more to this friday (even elements act as ref here because of the updateState)
+      ref: Partial<Ref<unknown>>,
       binding?: {
         event?: string;
         signalProperty: string;
@@ -118,45 +135,48 @@ declare module "cradova" {
    * @param {expression} condition
    * @param {function} elements[]
    */
-  export function assert(
+  export function assert<Type>(
     condition: boolean,
-    ...elements: VJS_Child_TYPE<HTMLElement>[]
-  ): VJS_Child_TYPE<HTMLElement> | undefined;
-
+    ...elements: VJS_Child_TYPE<Type | HTMLElement>[]
+  ): HTMLElement[];
   type LoopData<Type> = Type[];
-
   export function loop<Type>(
     datalist: LoopData<Type>,
     component: (
       value: Type,
       index?: number,
       array?: LoopData<Type>
-    ) => HTMLElement | undefined
-  ): HTMLElement | undefined;
-  export function assertOr(
+    ) => HTMLElement | DocumentFragment | undefined
+  ): HTMLElement[] | undefined;
+  export function assertOr<Type>(
     condition: boolean,
-    ifTrue: HTMLElement | HTMLElement[],
-    ifFalse: HTMLElement | HTMLElement[]
+    ifTrue: VJS_Child_TYPE<Type | HTMLElement>,
+    ifFalse: VJS_Child_TYPE<Type | HTMLElement>
   ): HTMLElement;
   /**
    * Cradova Ref
    * -------
    * create dynamic components
    */
-
   export class Ref<D> {
     private component;
     private effects;
     private effectuate;
     private rendered;
     private published;
-    private hasFirstStateUpdateRun;
     private preRendered;
     private reference;
     Signal: createSignal<any> | undefined;
+    _state: D[];
+    _state_track: {
+      [x: number]: boolean;
+    };
+    _state_index: number;
     stash: D | undefined;
-    constructor(component: (this: Ref<D>, data: D) => HTMLElement);
-    preRender(data?: D | undefined): void;
+    constructor(
+      component: (this: Ref<D>, data: D) => HTMLElement | DocumentFragment
+    );
+    preRender(data?: D): void;
     destroyPreRendered(): void;
     /**
      * Cradova Ref
@@ -165,33 +185,29 @@ declare module "cradova" {
      * @param data
      * @returns () => HTMLElement
      */
-    render(data?: D, stash?: boolean): HTMLElement;
+    render(data?: D, stash?: boolean): HTMLElement | DocumentFragment;
     instance(): Record<string, any>;
     _setExtra(Extra: createSignal<any>): void;
-    /**
-     * Cradova Ref
-     * ---
-     * runs on first state update
-     *
-     */
-    effect(fn: () => Promise<void> | void): void;
+    _roll_state(data: D, idx: number, get?: boolean): D;
+    _effect(fn: () => Promise<void> | void): void;
     private effector;
     /**
      * Cradova Ref
      * ---
      * update ref component with new data and update the dom.
      * @param data
-     * @returns void
-     *
-     *
-     * .
+     * @returns
      */
-    updateState(data: D, stash?: boolean): void;
+    updateState(data?: D, stash?: boolean): void;
     private Activate;
-    remove(): void;
   }
+  /**
+   * cradova
+   * ---
+   * lazy load a file
+   */
   export class lazy<Type> {
-    public content: Type | undefined;
+    content: Type | undefined;
     private _cb;
     constructor(cb: () => Promise<unknown>);
     load(): Promise<void>;
@@ -204,27 +220,106 @@ declare module "cradova" {
   export class reference {
     [x: string]: Record<string, any>;
     bindAs(name: string): reference;
-    // _appendDom(name: string, Element: HTMLElement): void;
     _appendDomForce(name: string, Element: HTMLElement): void;
   }
+  /**
+   * Cradova
+   * ---
+   *  Allows functional components to manage state by providing a state value and a function to update it.
+   * @param initialValue
+   * @param ActiveRef
+   * @returns [state, setState]
+   */
+  export function useState<S>(
+    initialValue: S,
+    ActiveRef: Ref<S>
+  ): (S | ((newState: S) => void))[];
+  /**
+ * Cradova
+ * ---
+Allows side effects to be performed in functional components (Refs), such as fetching data or subscribing to events.
+ * @param effect
+ * @returns
+ */
+  export function useEffect(effect: () => void, ActiveRef: Ref<unknown>): void;
+  /**
+ * Cradova
+ * ---
+Returns a mutable reference object of dom elements that persists across component renders.
+ * @returns reference
+ */
+  export function useRef(): Record<string, HTMLElement | undefined>;
 
-  type DataAttributes = { [key: `data-${string}`]: string };
-  type AriaAttributes = { [key: `aria-${string}`]: string };
+  /**
+   *  Cradova Screen
+   * ---
+   * create instances of manageable pages and scaffolds
+   * @param name
+   * @param template
+   * @param transitions
+   */
+  export class Screen {
+    /**
+     * this should be a cradova screen component
+     */
+    _html:
+      | ((this: Screen, data?: unknown) => HTMLElement | DocumentFragment)
+      | HTMLElement
+      | DocumentFragment;
+    /**
+     * this is a set of added html to the screen
+     */
+    _secondaryChildren: VJSType<HTMLElement>[];
+    /**
+     * error handler for the screen
+     */
+    _errorHandler: ((err: unknown) => void) | null;
+    /**
+     * used internally
+     */
+    _name: string;
+    private _packed;
+    private _template;
+    private _callBack;
+    private _deCallBack;
+    private _persist;
+    private _delegatedRoutesCount;
+    private _transition;
+    constructor(cradova_screen_initials: CradovaScreenType);
+    get _delegatedRoutes(): boolean;
+    set _delegatedRoutes(count: boolean);
+    setErrorHandler(errorHandler: (err: unknown) => void): void;
+    _package(): Promise<void>;
+    onActivate(cb: () => Promise<void> | void): void;
+    onDeactivate(cb: () => Promise<void> | void): void;
+    addChildren(...addOns: VJSType<HTMLElement>[]): void;
+    _deActivate(): Promise<void>;
+    _Activate(force?: boolean): Promise<void>;
+  }
 
+  type DataAttributes = {
+    [key: `data-${string}`]: string;
+  };
+  type AriaAttributes = {
+    [key: `aria-${string}`]: string;
+  };
   type VJSType<T> = (
     ...VJS: (
       | undefined
       | string
-      | Partial<T>
       | HTMLElement
       | HTMLElement[]
-      | DataAttributes
-      | AriaAttributes
+      | DocumentFragment
+      | DocumentFragment[]
+      | TemplateStringsArray
+      | Partial<T>
       | (() => HTMLElement)
+      | Partial<DataAttributes>
+      | Partial<AriaAttributes>
+      | Partial<CSSStyleDeclaration>
       | {
           style?: Partial<CSSStyleDeclaration>;
           onmount?: (this: T) => void;
-          text?: string;
           reference?: reference;
         }
     )[]
@@ -232,28 +327,39 @@ declare module "cradova" {
   type VJS_params_TYPE<T> = (
     | undefined
     | string
-    | Partial<T>
     | HTMLElement
     | HTMLElement[]
-    | Partial<CSSStyleDeclaration>
-    | DataAttributes
-    | AriaAttributes
+    | DocumentFragment
+    | DocumentFragment[]
     | TemplateStringsArray
+    | Partial<T>
     | (() => HTMLElement)
-    | any
+    | Partial<DataAttributes>
+    | Partial<AriaAttributes>
+    | Partial<CSSStyleDeclaration>
     | {
         style?: Partial<CSSStyleDeclaration>;
+        src?: string;
+        href?: string;
+        placeholder?: string;
+        type?: string;
+        action?: string;
+        name?: string;
+        alt?: string;
+        for?: string;
+        method?: string;
+        rows?: string;
+        value?: string;
+        target?: string;
+        rel?: string;
+        required?: string;
+        frameBorder?: string;
         onmount?: (this: T) => void;
-        text?: string;
         reference?: reference;
       }
   )[];
-
   type VJS_Child_TYPE<T> = undefined | string | T | (() => T);
-  /**
-   *
-   */
-  type CradovaScreenType = {
+  type CradovaScreenType<T = unknown> = {
     /**
      * Cradova screen
      * ---
@@ -277,13 +383,17 @@ declare module "cradova" {
      * @returns void
      * .
      */
-    template: ((this: Screen, data?: unknown) => HTMLElement) | HTMLElement;
+    template:
+      | ((this: Screen, data?: T | unknown) => HTMLElement | DocumentFragment)
+      | HTMLElement
+      | DocumentFragment;
     /**
      * Cradova screen
      * ---
      * Allows this screen render in parallel for unique routes
      *
      * limit is 1000
+     *
      * .
      */
     renderInParallel?: boolean;
@@ -296,54 +406,34 @@ declare module "cradova" {
      * .
      */
     persist?: boolean;
-    /**
-     * Cradova screen
-     * ---
-     * Should the loading screen be show as this screen is loading?
-     * .
-     */
-    suspend?: boolean;
   };
 
-  export const makeElement: (
-    element: HTMLElement,
-    ...ElementChildrenAndPropertyList: VJS_params_TYPE<HTMLElement>
-  ) => HTMLElement;
+  export const makeElement: <E extends HTMLElement>(
+    element: E & HTMLElement,
+    ElementChildrenAndPropertyList: VJS_params_TYPE<E>
+  ) => E;
   export const a: VJSType<HTMLAnchorElement>;
-  export const abbr: VJSType<HTMLElement>;
-  export const address: VJSType<HTMLElement>;
   export const area: VJSType<HTMLAreaElement>;
   export const article: VJSType<HTMLElement>;
   export const aside: VJSType<HTMLElement>;
   export const audio: VJSType<HTMLAudioElement>;
   export const b: VJSType<HTMLElement>;
   export const base: VJSType<HTMLBaseElement>;
-  export const bdi: VJSType<HTMLElement>;
-  export const bdo: VJSType<HTMLElement>;
   export const blockquote: VJSType<HTMLElement>;
-  export const body: VJSType<HTMLBodyElement>;
   export const br: VJSType<HTMLBRElement>;
   export const button: VJSType<HTMLButtonElement>;
   export const canvas: VJSType<HTMLCanvasElement>;
   export const caption: VJSType<HTMLTableCaptionElement>;
-  export const cite: VJSType<HTMLElement>;
   export const code: VJSType<HTMLElement>;
   export const col: VJSType<HTMLTableColElement>;
-  export const colgroup: VJSType<HTMLElement>;
+  export const colgroup: VJSType<HTMLOptGroupElement>;
   export const data: VJSType<HTMLDataElement>;
   export const datalist: VJSType<HTMLDataListElement>;
-  export const dd: VJSType<HTMLElement>;
-  export const del: VJSType<HTMLElement>;
   export const details: VJSType<HTMLDetailsElement>;
-  export const dfn: VJSType<HTMLElement>;
   export const dialog: VJSType<HTMLDialogElement>;
   export const div: VJSType<HTMLDivElement>;
-  export const dl: VJSType<HTMLElement>;
-  export const dt: VJSType<HTMLElement>;
   export const em: VJSType<HTMLElement>;
   export const embed: VJSType<HTMLEmbedElement>;
-  export const fieldset: VJSType<HTMLFieldSetElement>;
-  export const figcaption: VJSType<HTMLElement>;
   export const figure: VJSType<HTMLElement>;
   export const footer: VJSType<HTMLElement>;
   export const form: VJSType<HTMLFormElement>;
@@ -354,72 +444,45 @@ declare module "cradova" {
   export const h5: VJSType<HTMLHeadingElement>;
   export const h6: VJSType<HTMLHeadingElement>;
   export const head: VJSType<HTMLHeadElement>;
-  export const header: VJSType<HTMLElement>;
+  export const header: VJSType<HTMLHeadElement>;
   export const hr: VJSType<HTMLHRElement>;
-  export const html: VJSType<HTMLHtmlElement>;
-  export const i: VJSType<HTMLElement>;
+  export const i: VJSType<HTMLLIElement>;
   export const iframe: VJSType<HTMLIFrameElement>;
   export const img: VJSType<HTMLImageElement>;
   export const input: VJSType<HTMLInputElement>;
-  export const ins: VJSType<HTMLElement>;
-  export const kbd: VJSType<HTMLElement>;
   export const label: VJSType<HTMLLabelElement>;
   export const legend: VJSType<HTMLLegendElement>;
   export const li: VJSType<HTMLLIElement>;
   export const link: VJSType<HTMLLinkElement>;
   export const main: VJSType<HTMLElement>;
-  export const map: VJSType<HTMLMapElement>;
-  export const mark: VJSType<HTMLElement>;
-  export const math: VJSType<HTMLElement>;
   export const menu: VJSType<HTMLMenuElement>;
-  export const meta: VJSType<HTMLMetaElement>;
-  export const meter: VJSType<HTMLMeterElement>;
   export const nav: VJSType<HTMLElement>;
   export const object: VJSType<HTMLObjectElement>;
   export const ol: VJSType<HTMLOListElement>;
   export const optgroup: VJSType<HTMLOptGroupElement>;
   export const option: VJSType<HTMLOptionElement>;
-  export const output: VJSType<HTMLOutputElement>;
   export const p: VJSType<HTMLParagraphElement>;
-  export const picture: VJSType<HTMLPictureElement>;
-  export const portal: VJSType<HTMLElement>;
   export const pre: VJSType<HTMLPreElement>;
   export const progress: VJSType<HTMLProgressElement>;
   export const q: VJSType<HTMLQuoteElement>;
-  export const rp: VJSType<HTMLElement>;
-  export const rt: VJSType<HTMLElement>;
-  export const ruby: VJSType<HTMLElement>;
-  export const s: VJSType<HTMLElement>;
-  export const samp: VJSType<HTMLElement>;
-  export const script: VJSType<HTMLScriptElement>;
   export const section: VJSType<HTMLElement>;
   export const select: VJSType<HTMLSelectElement>;
-  export const slot: VJSType<HTMLSlotElement>;
-  export const small: VJSType<HTMLElement>;
   export const source: VJSType<HTMLSourceElement>;
   export const span: VJSType<HTMLSpanElement>;
   export const strong: VJSType<HTMLElement>;
-  export const style: VJSType<HTMLStyleElement>;
-  export const sub: VJSType<HTMLElement>;
   export const summary: VJSType<HTMLElement>;
-  export const sup: VJSType<HTMLElement>;
   export const table: VJSType<HTMLTableElement>;
   export const tbody: VJSType<HTMLTableColElement>;
   export const td: VJSType<HTMLTableCellElement>;
   export const template: VJSType<HTMLTemplateElement>;
   export const textarea: VJSType<HTMLTextAreaElement>;
-  export const tfoot: VJSType<HTMLElement>;
   export const th: VJSType<HTMLTableSectionElement>;
-  export const thead: VJSType<HTMLTableSectionElement>;
-  export const time: VJSType<HTMLTimeElement>;
   export const title: VJSType<HTMLTitleElement>;
   export const tr: VJSType<HTMLTableRowElement>;
   export const track: VJSType<HTMLTrackElement>;
-  export const u: VJSType<HTMLElement>;
+  export const u: VJSType<HTMLUListElement>;
   export const ul: VJSType<HTMLUListElement>;
-  export const val: VJSType<HTMLElement>;
   export const video: VJSType<HTMLVideoElement>;
-  export const wbr: VJSType<HTMLElement>;
 
   /** cradova router
    * ---
@@ -428,7 +491,7 @@ declare module "cradova" {
    * @param {string}   path     Route path.
    * @param  screen the cradova document tree for the route.
    */
-  class RouterClass {
+  export class RouterClass {
     /** cradova router
      * ---
      * Registers a route.
@@ -462,6 +525,16 @@ declare module "cradova" {
       data?: Record<string, unknown> | null,
       force?: boolean
     ): void;
+    /**
+     * Cradova
+     * ---
+     * Loading screen for your app
+     *
+     * lazy loaded loading use
+     *
+     * @param screen
+     */
+    setLoadingScreen(screen: Screen): void;
     /** cradova router
      * ---
      * Listen for navigation events
@@ -485,7 +558,7 @@ declare module "cradova" {
      *
      * .
      */
-    getParams: () => any;
+    getParams(): any;
     /**
      * Cradova
      * ---
@@ -495,71 +568,10 @@ declare module "cradova" {
      * @param path? page path
      */
     addErrorHandler(callback: (err: unknown) => void): void;
-    /**
-     * Cradova
-     * ---
-     * Loading screen for your app
-     *
-     * lazy loaded loading use
-     *
-     * @param screen
-     */
-    setLoadingScreen(screen: Screen): void;
-
     _mount(): void;
   }
   export const Router: RouterClass;
 
-  /**
-   *  Cradova Screen
-   * ---
-   * create instances of manageable pages and scaffolds
-   * @param name
-   * @param template
-   * @param transitions
-   */
-  export class Screen {
-    /**
-     * this should be a cradova screen component
-     */
-    _html: Function | HTMLElement;
-    /**
-     * this is a set of added html to the screen
-     */
-    _secondaryChildren: VJSType<HTMLElement>[];
-    /**
-     * error handler for the screen
-     */
-    _errorHandler: ((err: unknown) => void) | null;
-    /**
-     * used internally
-     */
-    _name: string;
-    private _packed;
-    private _template;
-    private _callBack;
-    private _deCallBack;
-    private _persist;
-    private _data;
-    // _params: Record<string, unknown> | null;
-    _suspend: boolean;
-    private _delegatedRoutesCount;
-    private _transition;
-    private _doc;
-    constructor(cradova_screen_initials: CradovaScreenType);
-    get _delegatedRoutes(): boolean;
-    set _delegatedRoutes(count: boolean);
-    // get _paramData(): typeof this._params;
-    // set _paramData(params: typeof this._params);
-    setErrorHandler(errorHandler: (err: unknown) => void): void;
-    _package(): Promise<void>;
-    onActivate(cb: () => Promise<void> | void): void;
-    onDeactivate(cb: () => Promise<void> | void): void;
-    addChildren(...addOns: VJSType<HTMLElement>[]): void;
-    _deActivate(): Promise<void>;
-    _Activate(force?: boolean): Promise<void>;
-  }
-
   /**
    *
    * Cradova Ajax
@@ -580,11 +592,11 @@ declare module "cradova" {
       } & Record<string, string>;
       callbacks?: Record<string, (arg: Function) => void>;
     }
-  ): Promise<unknown>;
+  ): Promise<string>;
 
-  type TemplateType = (
-    ...element_initials: VJS_params_TYPE<HTMLElement>
-  ) => HTMLElement;
+  type TemplateType = <E extends HTMLElement>(
+    ...element_initials: VJS_params_TYPE<E | HTMLElement>
+  ) => E | HTMLElement | DocumentFragment;
   /**
    * Cradova
    * ---