sigment/types/index.d.ts

A lightweight reactive JavaScript framework built with signals and vanilla JS — no virtual DOM, no JSX, no transpilation.

// index.d.ts


type ComponentLoader = () => Promise<{ default: (...args: any[]) => HTMLElement }>;

type ComponentMap = {
  [key: string]: ComponentLoader;
};


export type Route = {
  loader: () => Promise<any>;
  // `urlParam` allows a string pattern like '{id}/{pageid}' for dynamic route parameters
  urlParam?: string;  
  guard?: (params?: Record<string, any>) => boolean | Promise<boolean>;
  logic?: () => void;
  cacheExpiration?: number;
};

export type RoutesMap = Record<string, Route | string>;

/** 
 * The main app object with some properties and functions
 */
export declare const MyApp: {
  cleanHtml: (flag: boolean) => void;
  cleanhtml: true;
  setMaxCacheSize: (size: number) => void;
  maxCacheSize: number;
  setRoute: (routes: RoutesMap) => void;  // <-- updated to accept RoutesMap
  route: RoutesMap | null;                 // <-- updated here as well
};


export function NavigateTo(path: string): Promise<void>;
export function NavigateTo(path: string, stateful: boolean): Promise<void>;
export function NavigateTo(path: string, key: string): Promise<void>;
export function NavigateTo(path: string, key: string, stateful: boolean): Promise<void>;
export function NavigateTo(path: string, map: ComponentMap, stateful: boolean): Promise<void>;
export function NavigateTo(path: string, map: ComponentMap, key: string, stateful: boolean): Promise<void>;



/**
 * Creates a reactive effect that runs the given function and tracks dependencies.
 */
export declare function createEffect(fn: () => void): void;



/**
 * Adds a sigment with an optional native tag.
 * @param n - The segment identifier as a string.
 * @param nativeTag - An optional native tag as a string (defaults to null).
 */
export function createSigment(
  n: string,
  nativeTag?: string | null
): void;


/**
 * Adds a sigment with an optional native tag.
 * @param n - The segment identifier as a string.
 * @param nativeTag - An optional native tag as a string (defaults to null).
 */
export function addSigment(
  n: string,
  nativeTag?: string | null
): void;

/**
 * Fetches a URL with caching and TTL, returning parsed JSON.
 */
export declare function fetchCache<T = any>(
  url: string,
  ttl?: number,
  options?: RequestInit
): Promise<T>;

export interface MemoizeOptions {
  /**
   * Controls sorting of object keys before memoization cache key generation.
   * - true: Deep sort all nested object keys (default behavior).
   * - false: Shallow sort only top-level keys.
   * - undefined: No sorting (cache key uses raw arguments).
   */
  deepSort?: boolean;
}

/**
 * Memoizes the results of a function with optional TTL and key sorting.
 * 
 * @param fn The function to memoize.
 * @param ttl Time to live for cache entries in milliseconds. Defaults to 5000ms.
 * @param options Optional memoization options.
 * @returns The memoized function with a `.clear()` method to clear the cache.
 */
export function memoizeFunc<
  F extends (...args: any[]) => any
>(
  fn: F,
  ttl?: number,
  options?: MemoizeOptions
): F & { clear(): void };






/**
 * Parses a path given a user-defined routes object.
 */
export declare function parsePath(
  componentImports: RoutesMap
): {
  componentName: string;
  params: any | object;
};


/**
 * Loads a component and optionally runs logic, returning an HTMLElement.
 */
 export declare function loadRunFunc(
  componentMap: RoutesMap, 
  componentName: string,
  params?: Record<string, any> | null,
  logic?: (() => void) | null
): Promise<HTMLElement>;


/**
 * Clears cached component for a given component name.
 */
export declare function clearComponentCache(componentName: string): void;

export declare function createGlobalSignal<T>(key: string, initialValue: T): [() => T, (v: T) => void];

/**
 * Alias for createGlobalSignal.
 */
export { createGlobalSignal as globalSignal };



export declare function getGlobalSignal<T>(key: string): [() => T, (v: T) => void];

/**
 * Alias for getGlobalSignal.
 */

export { getGlobalSignal as useGlobalSignal };


/**
 * Creates a reactive signal with getter and setter.
 * Setter optionally accepts a second argument 'force' (boolean).
 */
export declare function createSignal<T = undefined>(
  initialValue?: T
): [() => T, (newValue: T, force?: boolean) => void];


/**
 * Alias for createSignal.
 */

export { createSignal as signal };


/**
 * Function gve creates an HTML element with the given name.
 */
export declare function gve(name: string): HTMLElement | null;
export { gve as getVirtualElementById };



export function gve(name: string): HTMLElement | null;

export { gve as getVirtualElementById };



/**
 * Sets a cookie; value can be string or object (will be JSON.stringified).
 */
export declare function setCookie(k: string, v: any, t?: number): void;

/**
 * Gets a cookie by key, returns string, parsed object, or null.
 */
export declare function getCookie(k: string): any;

/**
 * Sets localStorage item; value can be string, object, or HTMLElement (stored as outerHTML).
 */
export declare function setStorage(key: string, value: any): void;

/**
 * Gets localStorage item; parses JSON or returns string or HTMLElement-like object.
 */
export declare function getStorage(key: string): any;

/**
 * Hyperscript-style function to create elements or components.
 */
export declare function h(
  tag: string | ((props?: Record<string, any>, ...children: any[]) => HTMLElement | any),
  ...args: (Record<string, any> | string | number | HTMLElement | (() => string | HTMLElement) | Array<any>)[]
): HTMLElement;

/**
 * Groups and optionally executes components or HTML elements and metadata.
 */
export declare function gvec(
  obj: {
    [key: string]: any;
    param?: string | any[] | Record<string, any>;
  },
  s?: boolean,
  o?: Record<string, any>
): any;


/**
 * Checks if a value is undefined, null, or an empty string.
 * 
 * @param v - The value to check.
 * @returns True if empty, otherwise false.
 */
export declare function IsEmpty(v: any): boolean;

/**
 * Pushes a new state to the browser's history (for navigation).
 * 
 * @param path - The path to navigate to.
 */
export declare function Navigate(path: string): void;


/**
 * Loads a component module by name from a given map of dynamic import functions.
 * 
 * @param componentImports - An object mapping names to dynamic import functions.
 * @param componentName - The name of the component to load.
 * @returns A promise that resolves to the loaded component.
 */
export declare function loadFunc(
  componentImports: Record<string, () => Promise<any>>,
  componentName: string
): Promise<any>;


/**
 * Executes an RPC call with a function and a params object.
 * 
 * @param func - A function representing the RPC call body.
 * @param params - An object mapping method names to arrays of parameters.
 * @returns any
 */
export declare function rpc(
  func: Function,
  params: Record<string, any[]>
): any;

/**
 * Route function that checks if the current path matches the pattern and optional restrictions.
 *
 * @param pathPattern - The URL pattern string (e.g., "/admin/:id").
 * @param options - Optional object with passRestriction(s) functions.
 * @returns Promise resolving to boolean indicating match and restrictions pass.
 */
export declare function Route(
  pathPattern: string,
  options?: {
    passRestriction?: Array<(() => boolean | Promise<boolean>)> | (() => boolean | Promise<boolean>);
  }
): Promise<boolean>;




declare global {
	
 type Child =
  | string
  | number
  | boolean
  | null
  | undefined
  | HTMLElement
  | Text
  | DocumentFragment
  | (() => Child)
  | Child[];
  
  type Props = Partial<HTMLElement> & {
    [key: `data-${string}`]: string | number | boolean;
    [key: `aria-${string}`]: string | number | boolean;
    [key: string]: any; // allow fake attributes like fake-prop="123"
  };

  type TagFunction = {
    (props: Props, ...children: Child[]): HTMLElement;
    (...children: Child[]): HTMLElement;
  };


  const elements: string[];

  function createTagFunctions(tags: string[]): Record<string, TagFunction>;

  function a(props: Props, ...children: Child[]): HTMLElement;
  function a(...children: Child[]): HTMLElement;
  function abbr(props: Props, ...children: Child[]): HTMLElement;
  function abbr(...children: Child[]): HTMLElement;
  function area(props: Props, ...children: Child[]): HTMLElement;
  function area(...children: Child[]): HTMLElement;
  function article(props: Props, ...children: Child[]): HTMLElement;
  function article(...children: Child[]): HTMLElement;
  function aside(props: Props, ...children: Child[]): HTMLElement;
  function aside(...children: Child[]): HTMLElement;
  function audio(props: Props, ...children: Child[]): HTMLElement;
  function audio(...children: Child[]): HTMLElement;
  function base(props: Props, ...children: Child[]): HTMLElement;
  function base(...children: Child[]): HTMLElement;
  function b(props: Props, ...children: Child[]): HTMLElement;
  function b(...children: Child[]): HTMLElement;
  function bdi(props: Props, ...children: Child[]): HTMLElement;
  function bdi(...children: Child[]): HTMLElement;
  function bdo(props: Props, ...children: Child[]): HTMLElement;
  function bdo(...children: Child[]): HTMLElement;
  function blockquote(props: Props, ...children: Child[]): HTMLElement;
  function blockquote(...children: Child[]): HTMLElement;
  function body(props: Props, ...children: Child[]): HTMLElement;
  function body(...children: Child[]): HTMLElement;
  function br(props: Props, ...children: Child[]): HTMLElement;
  function br(...children: Child[]): HTMLElement;
  function button(props: Props, ...children: Child[]): HTMLElement;
  function button(...children: Child[]): HTMLElement;
  function canvas(props: Props, ...children: Child[]): HTMLElement;
  function canvas(...children: Child[]): HTMLElement;
  function cite(props: Props, ...children: Child[]): HTMLElement;
  function cite(...children: Child[]): HTMLElement;
  function code(props: Props, ...children: Child[]): HTMLElement;
  function code(...children: Child[]): HTMLElement;
  function col(props: Props, ...children: Child[]): HTMLElement;
  function col(...children: Child[]): HTMLElement;
  function colgroup(props: Props, ...children: Child[]): HTMLElement;
  function colgroup(...children: Child[]): HTMLElement;
  function data(props: Props, ...children: Child[]): HTMLElement;
  function data(...children: Child[]): HTMLElement;
  function datalist(props: Props, ...children: Child[]): HTMLElement;
  function datalist(...children: Child[]): HTMLElement;
  function dd(props: Props, ...children: Child[]): HTMLElement;
  function dd(...children: Child[]): HTMLElement;
  function del(props: Props, ...children: Child[]): HTMLElement;
  function del(...children: Child[]): HTMLElement;
  function details(props: Props, ...children: Child[]): HTMLElement;
  function details(...children: Child[]): HTMLElement;
  function dfn(props: Props, ...children: Child[]): HTMLElement;
  function dfn(...children: Child[]): HTMLElement;
  function dialog(props: Props, ...children: Child[]): HTMLElement;
  function dialog(...children: Child[]): HTMLElement;
  function div(props: Props, ...children: Child[]): HTMLElement;
  function div(...children: Child[]): HTMLElement;
  function dl(props: Props, ...children: Child[]): HTMLElement;
  function dl(...children: Child[]): HTMLElement;
  function dt(props: Props, ...children: Child[]): HTMLElement;
  function dt(...children: Child[]): HTMLElement;
  function em(props: Props, ...children: Child[]): HTMLElement;
  function em(...children: Child[]): HTMLElement;
  function embed(props: Props, ...children: Child[]): HTMLElement;
  function embed(...children: Child[]): HTMLElement;
  function fieldset(props: Props, ...children: Child[]): HTMLElement;
  function fieldset(...children: Child[]): HTMLElement;
  function figcaption(props: Props, ...children: Child[]): HTMLElement;
  function figcaption(...children: Child[]): HTMLElement;
  function figure(props: Props, ...children: Child[]): HTMLElement;
  function figure(...children: Child[]): HTMLElement;
  function footer(props: Props, ...children: Child[]): HTMLElement;
  function footer(...children: Child[]): HTMLElement;
  function form(props: Props, ...children: Child[]): HTMLElement;
  function form(...children: Child[]): HTMLElement;
  function h1(props: Props, ...children: Child[]): HTMLElement;
  function h1(...children: Child[]): HTMLElement;
  function h2(props: Props, ...children: Child[]): HTMLElement;
  function h2(...children: Child[]): HTMLElement;
  function h3(props: Props, ...children: Child[]): HTMLElement;
  function h3(...children: Child[]): HTMLElement;
  function h4(props: Props, ...children: Child[]): HTMLElement;
  function h4(...children: Child[]): HTMLElement;
  function h5(props: Props, ...children: Child[]): HTMLElement;
  function h5(...children: Child[]): HTMLElement;
  function h6(props: Props, ...children: Child[]): HTMLElement;
  function h6(...children: Child[]): HTMLElement;
  function head(props: Props, ...children: Child[]): HTMLElement;
  function head(...children: Child[]): HTMLElement;
  function header(props: Props, ...children: Child[]): HTMLElement;
  function header(...children: Child[]): HTMLElement;
  function hr(props: Props, ...children: Child[]): HTMLElement;
  function hr(...children: Child[]): HTMLElement;
  function html(props: Props, ...children: Child[]): HTMLElement;
  function html(...children: Child[]): HTMLElement;
  function i(props: Props, ...children: Child[]): HTMLElement;
  function i(...children: Child[]): HTMLElement;
  function iframe(props: Props, ...children: Child[]): HTMLElement;
  function iframe(...children: Child[]): HTMLElement;
  function img(props: Props, ...children: Child[]): HTMLElement;
  function img(...children: Child[]): HTMLElement;
  function input(props: Props, ...children: Child[]): HTMLElement;
  function input(...children: Child[]): HTMLElement;
  function ins(props: Props, ...children: Child[]): HTMLElement;
  function ins(...children: Child[]): HTMLElement;
  function kbd(props: Props, ...children: Child[]): HTMLElement;
  function kbd(...children: Child[]): HTMLElement;
  function label(props: Props, ...children: Child[]): HTMLElement;
  function label(...children: Child[]): HTMLElement;
  function legend(props: Props, ...children: Child[]): HTMLElement;
  function legend(...children: Child[]): HTMLElement;
  function li(props: Props, ...children: Child[]): HTMLElement;
  function li(...children: Child[]): HTMLElement;
  function link(props: Props, ...children: Child[]): HTMLElement;
  function link(...children: Child[]): HTMLElement;
  function main(props: Props, ...children: Child[]): HTMLElement;
  function main(...children: Child[]): HTMLElement;
  function map(props: Props, ...children: Child[]): HTMLElement;
  function map(...children: Child[]): HTMLElement;
  function mark(props: Props, ...children: Child[]): HTMLElement;
  function mark(...children: Child[]): HTMLElement;
  function menu(props: Props, ...children: Child[]): HTMLElement;
  function menu(...children: Child[]): HTMLElement;
  function meta(props: Props, ...children: Child[]): HTMLElement;
  function meta(...children: Child[]): HTMLElement;
  function meter(props: Props, ...children: Child[]): HTMLElement;
  function meter(...children: Child[]): HTMLElement;
  function nav(props: Props, ...children: Child[]): HTMLElement;
  function nav(...children: Child[]): HTMLElement;
  function noscript(props: Props, ...children: Child[]): HTMLElement;
  function noscript(...children: Child[]): HTMLElement;
  function object(props: Props, ...children: Child[]): HTMLElement;
  function object(...children: Child[]): HTMLElement;
  function ol(props: Props, ...children: Child[]): HTMLElement;
  function ol(...children: Child[]): HTMLElement;
  function optgroup(props: Props, ...children: Child[]): HTMLElement;
  function optgroup(...children: Child[]): HTMLElement;
  function option(props: Props, ...children: Child[]): HTMLElement;
  function option(...children: Child[]): HTMLElement;
  function output(props: Props, ...children: Child[]): HTMLElement;
  function output(...children: Child[]): HTMLElement;
  function p(props: Props, ...children: Child[]): HTMLElement;
  function p(...children: Child[]): HTMLElement;
  function param(props: Props, ...children: Child[]): HTMLElement;
  function param(...children: Child[]): HTMLElement;
  function picture(props: Props, ...children: Child[]): HTMLElement;
  function picture(...children: Child[]): HTMLElement;
  function pre(props: Props, ...children: Child[]): HTMLElement;
  function pre(...children: Child[]): HTMLElement;
  function progress(props: Props, ...children: Child[]): HTMLElement;
  function progress(...children: Child[]): HTMLElement;
  function q(props: Props, ...children: Child[]): HTMLElement;
  function q(...children: Child[]): HTMLElement;
  function rp(props: Props, ...children: Child[]): HTMLElement;
  function rp(...children: Child[]): HTMLElement;
  function rt(props: Props, ...children: Child[]): HTMLElement;
  function rt(...children: Child[]): HTMLElement;
  function ruby(props: Props, ...children: Child[]): HTMLElement;
  function ruby(...children: Child[]): HTMLElement;
  function s(props: Props, ...children: Child[]): HTMLElement;
  function s(...children: Child[]): HTMLElement;
  function samp(props: Props, ...children: Child[]): HTMLElement;
  function samp(...children: Child[]): HTMLElement;
  function script(props: Props, ...children: Child[]): HTMLElement;
  function script(...children: Child[]): HTMLElement;
  function section(props: Props, ...children: Child[]): HTMLElement;
  function section(...children: Child[]): HTMLElement;
  function select(props: Props, ...children: Child[]): HTMLElement;
  function select(...children: Child[]): HTMLElement;
  function slot(props: Props, ...children: Child[]): HTMLElement;
  function slot(...children: Child[]): HTMLElement;
  function small(props: Props, ...children: Child[]): HTMLElement;
  function small(...children: Child[]): HTMLElement;
  function source(props: Props, ...children: Child[]): HTMLElement;
  function source(...children: Child[]): HTMLElement;
  function span(props: Props, ...children: Child[]): HTMLElement;
  function span(...children: Child[]): HTMLElement;
  function strong(props: Props, ...children: Child[]): HTMLElement;
  function strong(...children: Child[]): HTMLElement;
  function style(props: Props, ...children: Child[]): HTMLElement;
  function style(...children: Child[]): HTMLElement;
  function sub(props: Props, ...children: Child[]): HTMLElement;
  function sub(...children: Child[]): HTMLElement;
  function summary(props: Props, ...children: Child[]): HTMLElement;
  function summary(...children: Child[]): HTMLElement;
  function sup(props: Props, ...children: Child[]): HTMLElement;
  function sup(...children: Child[]): HTMLElement;
  function table(props: Props, ...children: Child[]): HTMLElement;
  function table(...children: Child[]): HTMLElement;
  function tbody(props: Props, ...children: Child[]): HTMLElement;
  function tbody(...children: Child[]): HTMLElement;
  function td(props: Props, ...children: Child[]): HTMLElement;
  function td(...children: Child[]): HTMLElement;
  function template(props: Props, ...children: Child[]): HTMLElement;
  function template(...children: Child[]): HTMLElement;
  function textarea(props: Props, ...children: Child[]): HTMLElement;
  function textarea(...children: Child[]): HTMLElement;
  function tfoot(props: Props, ...children: Child[]): HTMLElement;
  function tfoot(...children: Child[]): HTMLElement;
  function th(props: Props, ...children: Child[]): HTMLElement;
  function th(...children: Child[]): HTMLElement;
  function thead(props: Props, ...children: Child[]): HTMLElement;
  function thead(...children: Child[]): HTMLElement;
  function time(props: Props, ...children: Child[]): HTMLElement;
  function time(...children: Child[]): HTMLElement;
  function title(props: Props, ...children: Child[]): HTMLElement;
  function title(...children: Child[]): HTMLElement;
  function tr(props: Props, ...children: Child[]): HTMLElement;
  function tr(...children: Child[]): HTMLElement;
  function track(props: Props, ...children: Child[]): HTMLElement;
  function track(...children: Child[]): HTMLElement;
  function u(props: Props, ...children: Child[]): HTMLElement;
  function u(...children: Child[]): HTMLElement;
  function ul(props: Props, ...children: Child[]): HTMLElement;
  function ul(...children: Child[]): HTMLElement;
  function var_(props: Props, ...children: Child[]): HTMLElement;
  function var_(...children: Child[]): HTMLElement;
  function video(props: Props, ...children: Child[]): HTMLElement;
  function video(...children: Child[]): HTMLElement;
  function wbr(props: Props, ...children: Child[]): HTMLElement;
  function wbr(...children: Child[]): HTMLElement;
  function fragment(props: Props, ...children: Child[]): DocumentFragment;
  function fragment(...children: Child[]): DocumentFragment;
  

}

/**
 * Mounts a node to a target element in the DOM.
 * @param selector - A string (element ID) or a DOM element to mount to.
 * @param node - A DOM Node to insert as the sole child of the target.
 * @throws Will throw an error if the target is not found.
 */
export function mount(
  selector: string | HTMLElement,
  node: Node
): void;

/**
 * Schedules the function `fn` to run after the browser completes the next paint cycle.
 * This uses two nested `requestAnimationFrame` calls to ensure the DOM is fully painted.
 * @param fn - A callback function to run after the next paint.
 */
export function onPaint(fn: () => void): void;

/**
 * Runs a function once, only after the first paint.
 * The function will not be called again, even if invoked multiple times.
 * @param fn - A callback function to run once after the first paint.
 */
export function paintFinish(fn: () => void): void;

/**
 * Updates the DOM element matching the selector with the given node,
 * only if needed.
 * @param target - A CSS selector string for the target element.
 * @param node - The new DOM Node to compare or replace.
 */
export function updateNodeIfNeeded(
  target: string,
  node: Node
): void;



declare global {
  declare module '*.module.css' {
    const classes: { [key: string]: string };
    export default classes;
  }

  declare module '*.css' {
    const content: string;
    export default content;
  }
}



export {};

export function createElement(tagName: string, ...args: (string | HTMLElement)[]): HTMLElement;