@unsetsoft/ryunixjs 1.2.3-canary.12 → 1.2.3-canary.13

package/dist/Ryunix.esm.js

@@ -70,7 +70,12 @@ const is = {
 };
 
 /**
- * Create text element
+ * The `createTextElement` function creates a text element with the specified text content.
+ * @param text - The `text` parameter in the `createTextElement` function is the text content that you
+ * want to create a text element for. This text will be set as the `nodeValue` of the text element in
+ * the returned object.
+ * @returns A text element object is being returned with a type of RYUNIX_TYPES.TEXT_ELEMENT and props
+ * containing the text value provided in the function argument.
  */
 const createTextElement = (text) => {
   return {
@@ -83,7 +88,21 @@ const createTextElement = (text) => {
 };
 
 /**
- * Create element
+ * The `createElement` function creates a virtual DOM element with specified type, properties, and
+ * children.
+ * @param type - The `type` parameter in the `createElement` function represents the type of element
+ * you want to create, such as a HTML tag like 'div', 'span', 'p', etc.
+ * @param props - The `props` parameter in the `createElement` function is an object that contains the
+ * properties or attributes for the element being created. These properties can include things like
+ * class names, styles, event handlers, and any other custom attributes you want to assign to the
+ * element. In the code snippet you provided,
+ * @param children - The `children` parameter in the `createElement` function represents the child
+ * elements or text content that will be nested within the created element. These children can be
+ * passed as arguments to the `createElement` function and will be rendered as part of the element's
+ * content.
+ * @returns An object is being returned with a `type` property representing the type of element, and a
+ * `props` property containing the element's properties. The `props` object includes the children of
+ * the element, which are processed to ensure they are in the correct format.
  */
 const createElement = (type, props, ...children) => {
   const safeProps = props || {};
@@ -102,7 +121,14 @@ const createElement = (type, props, ...children) => {
 };
 
 /**
- * Fragment component
+ * The `Fragment` function in JavaScript creates a fragment element with the given children.
+ * @param props - The `props` parameter in the `Fragment` function is an object that contains the
+ * properties passed to the `Fragment` component. These properties can include `children`, which
+ * represents the child elements or components nested within the `Fragment`.
+ * @returns The `Fragment` component is returning a Ryunix fragment element created using the
+ * `createElement` function. The element is of type `RYUNIX_TYPES.RYUNIX_FRAGMENT` and contains the
+ * children passed to the `Fragment` component. If `props.children` is not an array, it is converted
+ * into an array before being spread into the `createElement` function.
  */
 const Fragment = (props) => {
   const children = Array.isArray(props.children)
@@ -450,6 +476,9 @@ const updateDom = (dom, prevProps = {}, nextProps = {}) => {
     });
 };
 
+/**
+ * The `commitRoot` function commits the changes made to the virtual DOM by updating the actual DOM.
+ */
 const commitRoot = () => {
   const state = getState();
   state.deletions.forEach(commitWork);
@@ -618,12 +647,35 @@ const haveDepsChanged = (oldDeps, newDeps) => {
   return oldDeps.some((dep, i) => !Object.is(dep, newDeps[i]))
 };
 
+/**
+ * The `useStore` function in JavaScript is a custom hook that uses a reducer to manage state updates
+ * based on actions provided.
+ * @param initialState - The `initialState` parameter in the `useStore` function is the initial state
+ * of the store that will be used with the `useReducer` hook. It represents the starting state of the
+ * store before any actions are dispatched to update it.
+ * @returns The `useStore` function is returning the result of calling the `useReducer` hook with the
+ * `reducer` function and the `initialState` as arguments.
+ */
 const useStore = (initialState) => {
   const reducer = (state, action) =>
     is.function(action) ? action(state) : action;
   return useReducer(reducer, initialState)
 };
 
+/**
+ * The `useReducer` function in JavaScript is used to manage state and actions.
+ *
+ * @param reducer - The `reducer` parameter in the `useReducer` function is a function that specifies
+ * how the state should be updated in response to an action. It takes the current state and an action
+ * as arguments and returns the new state based on the action.
+ * @param initialState - The `initialState` parameter in the `useReducer` function represents the
+ * initial state of the reducer. It is the state that will be used when the reducer is first called or
+ * when the state needs to be reset. This initial state can be a simple value, an object, an array, or
+ * @param init - The `init` parameter in the `useReducer` function is an optional function that can be
+ * used to initialize the state. If provided, it will be called with the `initialState` as its argument
+ * and the return value will be used as the initial state for the reducer. If `init`
+ * @returns An array containing the current state and the dispatch function is being returned.
+ */
 const useReducer = (reducer, initialState, init) => {
   validateHookCall();
 
@@ -635,10 +687,9 @@ const useReducer = (reducer, initialState, init) => {
     hookID: hookIndex,
     type: RYUNIX_TYPES.RYUNIX_STORE,
     state: oldHook ? oldHook.state : init ? init(initialState) : initialState,
-    queue: [], // Siempre nueva cola vacía
+    queue: [],
   };
 
-  // Procesar acciones del render anterior
   if (oldHook?.queue) {
     oldHook.queue.forEach((action) => {
       try {
@@ -677,6 +728,16 @@ const useReducer = (reducer, initialState, init) => {
   return [hook.state, dispatch]
 };
 
+/**
+ * The `useEffect` function in JavaScript is used to manage side effects in functional components by
+ * comparing dependencies and executing a callback function when dependencies change.
+ * @param callback - The `callback` parameter in the `useEffect` function is a function that will be
+ * executed as the effect. This function can perform side effects like data fetching, subscriptions, or
+ * DOM manipulations.
+ * @param deps - The `deps` parameter in the `useEffect` function stands for dependencies. It is an
+ * optional array that contains values that the effect depends on. The effect will only re-run if any
+ * of the values in the `deps` array have changed since the last render. If the `deps` array
+ */
 const useEffect = (callback, deps) => {
   validateHookCall();
 
@@ -704,6 +765,14 @@ const useEffect = (callback, deps) => {
   state.hookIndex++;
 };
 
+/**
+ * The useRef function in JavaScript creates a reference object with an initial value for use in functional components.
+ * @param initialValue - The `initialValue` parameter in the `useRef` function represents the initial
+ * value that will be assigned to the `current` property of the reference object. This initial value
+ * will be used if there is no previous value stored in the hook.
+ * @returns The `useRef` function is returning the `current` property of the `hook.value` object, which
+ * contains the initial value passed to the `useRef` function.
+ */
 const useRef = (initialValue) => {
   validateHookCall();
 
@@ -722,6 +791,18 @@ const useRef = (initialValue) => {
   return hook.value
 };
 
+/**
+ * The useMemo function in JavaScript is used to memoize the result of a computation based on
+ * dependencies.
+ * @param compute - The `compute` parameter in the `useMemo` function is a callback function that
+ * calculates the value that `useMemo` will memoize and return. This function will be called to compute
+ * the memoized value when necessary.
+ * @param deps - The `deps` parameter in the `useMemo` function refers to an array of dependencies.
+ * These dependencies are used to determine whether the memoized value needs to be recalculated or if
+ * the previously calculated value can be reused. The `useMemo` hook will recompute the memoized value
+ * only if
+ * @returns The `useMemo` function is returning the `value` calculated by the `compute` function.
+ */
 const useMemo = (compute, deps) => {
   validateHookCall();
 
@@ -762,6 +843,17 @@ const useMemo = (compute, deps) => {
   return value
 };
 
+/**
+ * The useCallback function in JavaScript ensures that a callback function is memoized based on its
+ * dependencies.
+ * @param callback - A function that you want to memoize and return for later use.
+ * @param deps - The `deps` parameter in the `useCallback` function refers to an array of dependencies.
+ * These dependencies are used to determine when the callback function should be re-evaluated and
+ * memoized. If any of the dependencies change, the callback function will be re-executed and the
+ * memoized value will
+ * @returns The useCallback function is returning the memoized version of the callback function passed
+ * as the first argument, based on the dependencies array provided as the second argument.
+ */
 const useCallback = (callback, deps) => {
   if (!is.function(callback)) {
     throw new Error('useCallback requires a function as first argument')
@@ -769,6 +861,20 @@ const useCallback = (callback, deps) => {
   return useMemo(() => callback, deps)
 };
 
+/**
+ * The createContext function creates a context provider and useContext hook in JavaScript.
+ * @param [contextId] - The `contextId` parameter in the `createContext` function is used to specify
+ * the unique identifier for the context being created. It defaults to `RYUNIX_TYPES.RYUNIX_CONTEXT` if
+ * not provided.
+ * @param [defaultValue] - The `defaultValue` parameter in the `createContext` function is used to
+ * specify the default value that will be returned by the `useContext` hook if no provider is found in
+ * the component tree. It is an optional parameter, and if not provided, an empty object `{}` will be
+ * used as
+ * @returns The `createContext` function returns an object with two properties: `Provider` and
+ * `useContext`. The `Provider` property is a component that accepts `children` and `value` props, and
+ * sets the `_contextId` and `_contextValue` properties on the element. The `useContext` property is a
+ * hook function that retrieves the context value based on the context ID provided, or
+ */
 const createContext = (
   contextId = RYUNIX_TYPES.RYUNIX_CONTEXT,
   defaultValue = {},
@@ -806,6 +912,10 @@ const createContext = (
   return { Provider, useContext }
 };
 
+/**
+ * The `useQuery` function extracts query parameters from the URL in a browser environment.
+ * @returns An object containing the query parameters from the current URL is being returned.
+ */
 const useQuery = () => {
   if (typeof window === 'undefined') return {}
 
@@ -817,6 +927,14 @@ const useQuery = () => {
   return query
 };
 
+/**
+ * The function `useHash` in JavaScript is used to manage and update the hash portion of the URL in a
+ * web application.
+ * @returns The `useHash` function returns the current hash value from the window's location. If the
+ * window is undefined (e.g., in a server-side environment), it returns an empty string. The function
+ * also sets up an event listener to update the hash value when the hash in the URL changes and removes
+ * the event listener when the component unmounts.
+ */
 const useHash = () => {
   if (typeof window === 'undefined') return ''
 
@@ -829,6 +947,25 @@ const useHash = () => {
   return hash
 };
 
+/**
+ * The `useMetadata` function in JavaScript is used to dynamically update metadata tags in the document
+ * head based on provided tags and options.
+ * @param [tags] - The `tags` parameter in the `useMetadata` function is an object that contains
+ * metadata information for the webpage. It can include properties like `pageTitle`, `canonical`, and
+ * other custom metadata tags like `og:title`, `og:description`, `twitter:title`,
+ * `twitter:description`, etc. These tags
+ * @param [options] - The `options` parameter in the `useMetadata` function is an object that can
+ * contain the following properties:
+ * - `title`: An object that can have the following properties:
+ *  - `template`: A string that defines the template for the page title. It can include a placeholder
+ * `%s` that will be replaced with the actual page title.
+ * - `prefix`: A string that will be used as the default title if no specific page title is provided.
+ * @returns The `useMetadata` function does not return anything. It is a custom hook that updates the
+ * document's metadata (such as title and meta tags) based on the provided `tags` and `options` whenever
+ * they change.
+ * This hook can't be reached by google crawler.
+ */
+
 const useMetadata = (tags = {}, options = {}) => {
   useEffect(() => {
     if (typeof document === 'undefined') return
@@ -919,6 +1056,12 @@ const findRoute = (routes, path) => {
   return notFound
 };
 
+/**
+ * The `RouterProvider` component manages routing in a Ryunix application by updating the location based
+ * on window events and providing context for the current route.
+ * @returns The `RouterProvider` component is returning a `RouterContext.Provider` component with a
+ * `value` prop set to `contextValue`, and wrapping the `children` within a `Fragment`.
+ */
 const RouterProvider = ({ routes, children }) => {
   const [location, setLocation] = useStore(window.location.pathname);
 
@@ -955,10 +1098,24 @@ const RouterProvider = ({ routes, children }) => {
   )
 };
 
+/**
+ * The function `useRouter` returns the context of the Router for navigation in a Ryunix application.
+ * @returns The `useRouter` function is returning the result of calling
+ * `RouterContext.useContext('ryunix.navigation')`. This function is likely attempting to retrieve the
+ * navigation context from the RouterContext.
+ */
 const useRouter = () => {
   return RouterContext.useContext('ryunix.navigation')
 };
 
+/**
+ * The `Children` function in JavaScript uses router hooks to handle scrolling to a specific element
+ * based on the hash in the URL.
+ * @returns The `Children` component is returning the result of calling `createElement` with
+ * `route.component` as the first argument and an object with `key`, `params`, `query`, and `hash`
+ * properties as the second argument. The `key` property is set to `location`, and the `params`,
+ * `query`, and `hash` properties are passed as values from the component's props.
+ */
 const Children = () => {
   const { route, params, query, location } = useRouter();
   if (!route || !route.component) return null
@@ -980,6 +1137,12 @@ const Children = () => {
   })
 };
 
+/**
+ * The NavLink function in JavaScript is a component that generates a link element with customizable
+ * classes and active state based on the current location.
+ * @returns The `NavLink` component is returning a JSX element representing an anchor (`<a>`) tag with
+ * the following attributes and properties:
+ */
 const NavLink = ({ to, exact = false, ...props }) => {
   const { location, navigate } = useRouter();
   const isActive = exact ? location === to : location.startsWith(to);
@@ -1116,7 +1279,12 @@ const updateHostComponent = (fiber) => {
   reconcileChildren(fiber, children);
 };
 
-/* Image component */
+/**
+ * The Component `Image` takes in a `src` and other props, and returns an `img` element with the
+ * specified `src` and props.
+ * @returns The `Image` component is being returned. It is a functional component that renders an `img`
+ * element with the specified `src` and other props passed to it.
+ */
 const Image = ({ src, ...props }) => {
   return createElement('img', { ...props, src })
 };
@@ -1400,6 +1568,17 @@ const scheduleWork = (root, priority = Priority.NORMAL) => {
   }
 };
 
+/**
+ * The `render` function in JavaScript updates the DOM with a new element and schedules work to be done
+ * on the element.
+ * @param element - The `element` parameter in the `render` function is the element that you want to
+ * render in the specified container. It could be a DOM element, a component, or any other valid
+ * element that you want to display on the screen.
+ * @param container - The `container` parameter in the `render` function is the DOM element where the
+ * `element` will be rendered. It is the target container where the element will be appended as a
+ * child.
+ * @returns The `render` function is returning the `state.wipRoot` object.
+ */
 const render = (element, container) => {
   const state = getState();
   state.wipRoot = {
@@ -1416,6 +1595,17 @@ const render = (element, container) => {
   return state.wipRoot
 };
 
+/**
+ * The `init` function initializes a rendering process for a main element within a specified container
+ * root element.
+ * @param MainElement - MainElement is the main component or element that you want to render on the
+ * webpage. It could be a React component, a DOM element, or any other element that you want to display
+ * on the page.
+ * @param [root=__ryunix] - The `root` parameter in the `init` function is a default parameter with the
+ * value `'__ryunix'`. If no value is provided for `root` when calling the `init` function, it will
+ * default to `'__ryunix'`.
+ * @returns The `renderProcess` function is being returned from the `init` function.
+ */
 const init = (MainElement, root = '__ryunix') => {
   const state = getState();
   state.containerRoot = document.getElementById(root);
@@ -1505,7 +1695,11 @@ let isBatching = false;
 let pendingUpdates = [];
 
 /**
- * Batch multiple state updates into single render
+ * The `batchUpdates` function in JavaScript allows for batching multiple updates and flushing them all
+ * at once.
+ * @param callback - The `callback` parameter in the `batchUpdates` function is a function that will be
+ * executed within a batch update. This function can contain multiple updates that need to be processed
+ * together in a batch to improve performance and avoid unnecessary re-renders.
  */
 const batchUpdates = (callback) => {
   const wasBatching = isBatching;
@@ -1523,7 +1717,9 @@ const batchUpdates = (callback) => {
 };
 
 /**
- * Flush all pending updates
+ * The `flushUpdates` function processes and executes pending updates stored in an array.
+ * @returns If the `pendingUpdates` array is empty, the `flushUpdates` function will return nothing
+ * (undefined).
  */
 const flushUpdates = () => {
   if (pendingUpdates.length === 0) return