@relax.js/core 1.0.0

package/dist/lib/routing/RouteLink.d.ts

@@ -0,0 +1,7 @@
+export declare class RouteLink extends HTMLElement {
+    static get observedAttributes(): string[];
+    constructor();
+    private handleClick;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}

package/dist/lib/routing/Routing.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Single Page Application routing system with multiple target support.
+ * Designed for scenarios where you need:
+ * - Multiple navigation targets (main content, modals, sidebars)
+ * - Strongly typed route parameters
+ * - History management with back/forward support
+ *
+ * @example
+ * // Configure routes
+ * const routes = [
+ *   { name: 'user', path: '/users/:id' },          // String parameter
+ *   { name: 'order', path: '/orders/;orderId' },   // Number parameter
+ *   { name: 'modal', path: '/detail/:id', target: 'modal' }  // Custom target
+ * ];
+ */
+type WebComponentConstructor = new (...args: any[]) => HTMLElement;
+export declare enum GuardResult {
+    /**
+     * Handle route without checking more guards.
+     */
+    Allow = 0,
+    /**
+     * Throw a RouteGuardError.
+     */
+    Deny = 1,
+    /**
+     * Resume and check other guards.
+     */
+    Continue = 2,
+    /**
+     * Do not invoke the rooute nor other guards.
+     */
+    Stop = 3
+}
+export interface RouteGuard {
+    check(route: RouteMatchResult): GuardResult;
+}
+export interface Route {
+    name?: string;
+    target?: string;
+    path: string;
+    /**
+     * HTML file name (without extension).
+     *
+     * Define for instance if you have a route that requires a more limited layout. The library
+     * will automatically load that HTML file and rewrite URL history so that the correct url is displayed.
+     */
+    layout?: string;
+    /**
+     * Name of the tag for your web component.
+     */
+    componentTagName?: string;
+    /**
+     * Guards used to check if this route can be visited.
+     */
+    guards?: RouteGuard[];
+    component?: WebComponentConstructor;
+}
+export declare const internalRoutes: Route[];
+export declare const MyData: {
+    routes: any[];
+};
+/**
+ * Debug helper to print all registered routes to console.
+ */
+export declare function printRoutes(): void;
+/**
+ * Registers application routes with the router.
+ * Call this at application startup before routing begins.
+ *
+ * @param appRoutes - Array of route configurations
+ * @throws Error if referenced components are not registered
+ *
+ * @example
+ * const routes: Route[] = [
+ *     { name: 'home', path: '/', componentTagName: 'app-home' },
+ *     { name: 'user', path: '/users/:id', componentTagName: 'user-profile' },
+ *     { name: 'login', path: '/auth/', componentTagName: 'login-form', layout: 'noauth' }
+ * ];
+ * defineRoutes(routes);
+ */
+export declare function defineRoutes(appRoutes: Route[]): void;
+export type RouteParamType = string | number;
+export type RouteData = Record<string, RouteParamType>;
+/**
+ * Implement to receive typed route parameters via a `routeData` property.
+ * RouteTarget assigns `routeData` after element creation but before DOM insertion.
+ * Optional since it's not available at construction time.
+ *
+ * For convention-based usage without undefined checks, skip the interface
+ * and declare `routeData` directly on your component.
+ *
+ * @example
+ * class UserProfile extends HTMLElement implements Routable<{ userName: string }> {
+ *     routeData?: { userName: string };
+ * }
+ */
+export interface Routable<T extends RouteData = RouteData> {
+    routeData?: T;
+}
+/**
+ * Implement to run async initialization before the component is added to the DOM.
+ * RouteTarget calls `loadRoute()` and awaits it before inserting the element.
+ *
+ * @example
+ * class OrderDetail extends HTMLElement implements LoadRoute<{ orderId: number }> {
+ *     async loadRoute(data: { orderId: number }) {
+ *         this.order = await fetchOrder(data.orderId);
+ *     }
+ * }
+ */
+export interface LoadRoute<T extends RouteData = RouteData> {
+    loadRoute(data: T): void | Promise<void>;
+}
+/**
+ * Event sent to routing targets when a new route should be displayed.
+ */
+export declare class NavigateRouteEvent extends Event {
+    /**
+     * Matched route.
+     */
+    route: Route;
+    /**
+     * The generated url sements which can be used to push the url into the browser history.
+     */
+    urlSegments: string[];
+    /**
+     * Data supplied to the route.
+     */
+    routeData?: RouteData;
+    /**
+     * The target can differ from the default target that is defined in the route.
+     *
+     * undefined means that the default (unnamed) target should be used.
+     */
+    routeTarget?: string;
+    static NAME: string;
+    constructor(
+    /**
+     * Matched route.
+     */
+    route: Route, 
+    /**
+     * The generated url sements which can be used to push the url into the browser history.
+     */
+    urlSegments: string[], 
+    /**
+     * Data supplied to the route.
+     */
+    routeData?: RouteData, 
+    /**
+     * The target can differ from the default target that is defined in the route.
+     *
+     * undefined means that the default (unnamed) target should be used.
+     */
+    routeTarget?: string, eventInit?: EventInit);
+}
+declare global {
+    interface HTMLElementEventMap {
+        'rlx.navigateRoute': NavigateRouteEvent;
+    }
+    interface DocumentEventMap {
+        'rlx.navigateRoute': NavigateRouteEvent;
+    }
+}
+/**
+ * Result from route matching operations.
+ * Contains all information needed for navigation and rendering.
+ */
+export type RouteMatchResult = {
+    /**
+     * Matched route configuration
+     */
+    route: Route;
+    /**
+     * URL segments used for history state
+     */
+    urlSegments: string[];
+    /**
+     * Extracted and type-converted parameters
+     */
+    params: RouteData;
+};
+/**
+ * Supported types of route segments
+ */
+export type RouteSegmentType = 'string' | 'number' | 'path' | 'regex';
+/**
+ * Strongly typed route segment value
+ */
+export interface RouteValue {
+    /**
+     * Type of parameter for validation
+     */
+    type: RouteSegmentType;
+    /**
+     * Actual parameter value
+     */
+    value: any;
+}
+export declare class RouteError extends Error {
+}
+export declare class RouteGuardError extends RouteError {
+    isGuard: any;
+}
+export interface NavigateOptions {
+    /**
+     * Optional parameters when using route name
+     */
+    params?: Record<string, string | number>;
+    /**
+     * override for route's default target
+     */
+    target?: string;
+    /**
+     * When you want to override routes from the globally registered ones.
+     */
+    routes?: Route[];
+}
+/**
+ * Initializes routing and navigates to the current URL.
+ * Call this after DOM is ready and routes are defined.
+ *
+ * @example
+ * // In your main application component
+ * connectedCallback() {
+ *     defineRoutes(routes);
+ *     startRouting();
+ * }
+ */
+export declare function startRouting(): void;
+/**
+ * Navigates to a route by name or URL.
+ * Updates browser history and dispatches navigation events.
+ *
+ * @param routeNameOrUrl - Route name or URL path to navigate to
+ * @param options - Navigation options including params and target
+ *
+ * @example
+ * // Navigate by route name
+ * navigate('user', { params: { id: '123' } });
+ *
+ * // Navigate by URL
+ * navigate('/users/123');
+ *
+ * // Navigate to specific target
+ * navigate('detail', { params: { id: '42' }, target: 'modal' });
+ */
+export declare function navigate(routeNameOrUrl: string, options?: NavigateOptions): void;
+/**
+ * Match route by either name or URL pattern
+ * @param routes Available routes
+ * @param routeNameOrUrl Route name or URL to match
+ * @param routeData Optional parameters for named routes
+ */
+export declare function matchRoute(routes: Route[], routeNameOrUrl: string, routeData?: Record<string, string | any>): RouteMatchResult | null;
+/**
+ * Find route by name and apply parameters
+ * @param routes Available routes
+ * @param name Route name to find
+ * @param routeData Parameters to apply
+ */
+export declare function findRouteByName(routes: Route[], name: string, routeData?: Record<string, string | any>): RouteMatchResult | null;
+/**
+ * Find route matching URL pattern
+ * @param routes Available routes
+ * @param path URL to match
+ */
+export declare function findRouteByUrl(routes: Route[], path: string): RouteMatchResult | null;
+export {};

package/dist/lib/routing/RoutingTarget.d.ts

@@ -0,0 +1,22 @@
+/**
+ * WebComponent that listens on the `NavigateRouteEvent` event to be able to switch route.
+ *
+ * Use the "name" attribute to make this non-default target.
+ * Use the "dialog" attribute to render routes inside a native `<dialog>` element
+ * with built-in focus trapping, backdrop, and Escape-to-close.
+ *
+ * @example
+ * <r-route-target></r-route-target>
+ * <r-route-target name="modal" dialog></r-route-target>
+ */
+export declare class RouteTarget extends HTMLElement {
+    name?: string;
+    private dialog?;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private onNavigate;
+    private loadComponent;
+    /** Closes the dialog (only applies to dialog targets). */
+    close(): void;
+    private applyRouteData;
+}

package/dist/lib/routing/index.d.ts

@@ -0,0 +1,7 @@
+export { GuardResult, RouteGuard, Route, RouteParamType, RouteData, Routable, LoadRoute, RouteError, RouteGuardError, NavigateOptions, RouteMatchResult, RouteSegmentType, RouteValue, } from './types';
+export { NavigateRouteEvent } from './NavigateRouteEvent';
+export { registerRouteTarget, unregisterRouteTarget, clearPendingNavigations, } from './routeTargetRegistry';
+export { matchRoute, findRouteByName, findRouteByUrl, } from './routeMatching';
+export { internalRoutes, defineRoutes, startRouting, navigate, printRoutes, } from './navigation';
+export { RouteLink } from './RouteLink';
+export { RouteTarget } from './RoutingTarget';

package/dist/lib/routing/navigation.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Single Page Application routing system with multiple target support.
+ * Designed for scenarios where you need:
+ * - Multiple navigation targets (main content, modals, sidebars)
+ * - Strongly typed route parameters
+ * - History management with back/forward support
+ *
+ * @example
+ * // Configure routes
+ * const routes = [
+ *   { name: 'user', path: '/users/:id' },          // String parameter
+ *   { name: 'order', path: '/orders/;orderId' },   // Number parameter
+ *   { name: 'modal', path: '/detail/:id', target: 'modal' }  // Custom target
+ * ];
+ */
+import { type Route, type NavigateOptions } from './types';
+export declare const internalRoutes: Route[];
+export declare const MyData: {
+    routes: any[];
+};
+/**
+ * Debug helper to print all registered routes to console.
+ */
+export declare function printRoutes(): void;
+/**
+ * Registers application routes with the router.
+ * Call this at application startup before routing begins.
+ *
+ * @param appRoutes - Array of route configurations
+ * @throws Error if referenced components are not registered
+ *
+ * @example
+ * const routes: Route[] = [
+ *     { name: 'home', path: '/', componentTagName: 'app-home' },
+ *     { name: 'user', path: '/users/:id', componentTagName: 'user-profile' },
+ *     { name: 'login', path: '/auth/', componentTagName: 'login-form', layout: 'noauth' }
+ * ];
+ * defineRoutes(routes);
+ */
+export declare function defineRoutes(appRoutes: Route[]): void;
+/**
+ * Initializes routing and navigates to the current URL.
+ * Call this after DOM is ready and routes are defined.
+ *
+ * @example
+ * // In your main application component
+ * connectedCallback() {
+ *     defineRoutes(routes);
+ *     startRouting();
+ * }
+ */
+export declare function startRouting(): void;
+/**
+ * Navigates to a route by name or URL.
+ * Updates browser history and dispatches navigation events.
+ *
+ * @param routeNameOrUrl - Route name or URL path to navigate to
+ * @param options - Navigation options including params and target
+ *
+ * @example
+ * // Navigate by route name
+ * navigate('user', { params: { id: '123' } });
+ *
+ * // Navigate by URL
+ * navigate('/users/123');
+ *
+ * // Navigate to specific target
+ * navigate('detail', { params: { id: '42' }, target: 'modal' });
+ */
+export declare function navigate(routeNameOrUrl: string, options?: NavigateOptions): void;

package/dist/lib/routing/routeMatching.d.ts

@@ -0,0 +1,21 @@
+import type { Route, RouteMatchResult } from './types';
+/**
+ * Match route by either name or URL pattern
+ * @param routes Available routes
+ * @param routeNameOrUrl Route name or URL to match
+ * @param routeData Optional parameters for named routes
+ */
+export declare function matchRoute(routes: Route[], routeNameOrUrl: string, routeData?: Record<string, string | any>): RouteMatchResult | null;
+/**
+ * Find route by name and apply parameters
+ * @param routes Available routes
+ * @param name Route name to find
+ * @param routeData Parameters to apply
+ */
+export declare function findRouteByName(routes: Route[], name: string, routeData?: Record<string, string | any>): RouteMatchResult | null;
+/**
+ * Find route matching URL pattern
+ * @param routes Available routes
+ * @param path URL to match
+ */
+export declare function findRouteByUrl(routes: Route[], path: string): RouteMatchResult | null;

package/dist/lib/routing/routeTargetRegistry.d.ts

@@ -0,0 +1,23 @@
+import { NavigateRouteEvent } from './NavigateRouteEvent';
+type RouteTargetHandler = (evt: NavigateRouteEvent) => void;
+/**
+ * Registers a route target handler.
+ * When a navigation event targets this name, the handler is called directly.
+ * If a pending event exists for this target, it is replayed immediately.
+ *
+ * @param name - Target name, or `undefined` for the default (unnamed) target
+ * @param handler - Callback that receives the `NavigateRouteEvent`
+ *
+ * @example
+ * registerRouteTarget('sidebar', (evt) => renderComponent(evt));
+ */
+export declare function registerRouteTarget(name: string | undefined, handler: RouteTargetHandler): void;
+/**
+ * Unregisters a previously registered route target handler.
+ *
+ * @param name - Target name that was passed to `registerRouteTarget`
+ */
+export declare function unregisterRouteTarget(name: string | undefined): void;
+export declare function clearPendingNavigations(): void;
+export declare function initRouteTargetListener(): void;
+export {};

package/dist/lib/routing/types.d.ts

@@ -0,0 +1,130 @@
+type WebComponentConstructor = new (...args: any[]) => HTMLElement;
+export declare enum GuardResult {
+    /**
+     * Handle route without checking more guards.
+     */
+    Allow = 0,
+    /**
+     * Throw a RouteGuardError.
+     */
+    Deny = 1,
+    /**
+     * Resume and check other guards.
+     */
+    Continue = 2,
+    /**
+     * Do not invoke the rooute nor other guards.
+     */
+    Stop = 3
+}
+export interface RouteGuard {
+    check(route: RouteMatchResult): GuardResult;
+}
+export interface Route {
+    name?: string;
+    target?: string;
+    path: string;
+    /**
+     * HTML file name (without extension).
+     *
+     * Define for instance if you have a route that requires a more limited layout. The library
+     * will automatically load that HTML file and rewrite URL history so that the correct url is displayed.
+     */
+    layout?: string;
+    /**
+     * Name of the tag for your web component.
+     */
+    componentTagName?: string;
+    /**
+     * Guards used to check if this route can be visited.
+     */
+    guards?: RouteGuard[];
+    component?: WebComponentConstructor;
+}
+export type RouteParamType = string | number;
+export type RouteData = Record<string, RouteParamType>;
+/**
+ * Implement to receive typed route parameters via a `routeData` property.
+ * RouteTarget assigns `routeData` after element creation but before DOM insertion.
+ * Optional since it's not available at construction time.
+ *
+ * For convention-based usage without undefined checks, skip the interface
+ * and declare `routeData` directly on your component.
+ *
+ * @example
+ * class UserProfile extends HTMLElement implements Routable<{ userName: string }> {
+ *     routeData?: { userName: string };
+ * }
+ */
+export interface Routable<T extends RouteData = RouteData> {
+    routeData?: T;
+}
+/**
+ * Implement to run async initialization before the component is added to the DOM.
+ * RouteTarget calls `loadRoute()` and awaits it before inserting the element.
+ *
+ * @example
+ * class OrderDetail extends HTMLElement implements LoadRoute<{ orderId: number }> {
+ *     async loadRoute(data: { orderId: number }) {
+ *         this.order = await fetchOrder(data.orderId);
+ *     }
+ * }
+ */
+export interface LoadRoute<T extends RouteData = RouteData> {
+    loadRoute(data: T): void | Promise<void>;
+}
+/**
+ * Result from route matching operations.
+ * Contains all information needed for navigation and rendering.
+ */
+export type RouteMatchResult = {
+    /**
+     * Matched route configuration
+     */
+    route: Route;
+    /**
+     * URL segments used for history state
+     */
+    urlSegments: string[];
+    /**
+     * Extracted and type-converted parameters
+     */
+    params: RouteData;
+};
+/**
+ * Supported types of route segments
+ */
+export type RouteSegmentType = 'string' | 'number' | 'path' | 'regex';
+/**
+ * Strongly typed route segment value
+ */
+export interface RouteValue {
+    /**
+     * Type of parameter for validation
+     */
+    type: RouteSegmentType;
+    /**
+     * Actual parameter value
+     */
+    value: any;
+}
+export declare class RouteError extends Error {
+}
+export declare class RouteGuardError extends RouteError {
+    isGuard: any;
+}
+export interface NavigateOptions {
+    /**
+     * Optional parameters when using route name
+     */
+    params?: Record<string, string | number>;
+    /**
+     * override for route's default target
+     */
+    target?: string;
+    /**
+     * When you want to override routes from the globally registered ones.
+     */
+    routes?: Route[];
+}
+export {};

package/dist/lib/templates/NodeTemplate.d.ts

@@ -0,0 +1,38 @@
+import { ArgToken } from "./tokenizer";
+type ClickBinding = {
+    path: number[];
+    methodName: string;
+    argTokens: ArgToken[];
+};
+type BoundBinding = {
+    type: 'text';
+    node: Node;
+    func: (context: Record<string, any>, node: Node) => void;
+} | {
+    type: 'attribute';
+    element: HTMLElement;
+    name: string;
+    func: (context: Record<string, any>, element: HTMLElement) => void;
+};
+export declare class BoundNode {
+    private readonly root;
+    private readonly bindings;
+    private readonly clickBindings;
+    private readonly component?;
+    constructor(root: HTMLElement, bindings: BoundBinding[], clickBindings: ClickBinding[], component?: Record<string, any>);
+    render(data: Record<string, any>): HTMLElement;
+    private getNodeAtPath;
+}
+export declare function createBluePrint(html: string): Blueprint;
+export declare class Blueprint {
+    private readonly template;
+    private readonly bindings;
+    private readonly clickBindings;
+    constructor(htmlOrTemplate: string | HTMLTemplateElement);
+    createInstance(component?: Record<string, any>): BoundNode;
+    private getRootElement;
+    private collectBindings;
+    private collectClickBindings;
+    private getNodeAtPath;
+}
+export {};

package/dist/lib/templates/accessorParser.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Represents a single step in a property access path
+ * Can be either a property name or an array index access
+ * @example { type: "property", key: "user" }
+ * @example { type: "index", key: "0" }
+ */
+type PathSegment = {
+    type: "property" | "index";
+    key: string;
+};
+/**
+ * Represents the result of parsing a dot-notation string into path segments
+ * Used internally by the parser to break down property access chains including arrays
+ * @example [{ type: "property", key: "users" }, { type: "index", key: "0" }, { type: "property", key: "name" }] for "users[0].name"
+ */
+type PropertyPath = PathSegment[];
+/**
+ * Function type that accesses nested properties safely from a record
+ * Returns undefined if any property in the chain is missing or null/undefined
+ * @example
+ * const accessor = createAccessor("user.name");
+ * const result = accessor(data); // string | undefined
+ */
+type PropertyAccessor<T = unknown> = (record: Record<string, any>) => T | undefined;
+/**
+ * Parser configuration options for customizing dot-notation parsing behavior
+ * Used to modify how the parser handles property paths and edge cases
+ * @example { delimiter: ".", escapeChar: "\\" }
+ */
+interface ParserOptions {
+    delimiter?: string;
+    escapeChar?: string;
+}
+/**
+ * Parses a dot-notation string with array support into path segments
+ * Handles escaped delimiters, array indices, and validates input format
+ * @param notation - Notation string with dots and brackets (e.g., "users[0].profile.name")
+ * @param options - Parser configuration options
+ * @returns Array of path segments for property and array access
+ * @example
+ * parsePath("user.profile.name") // [{ type: "property", key: "user" }, { type: "property", key: "profile" }, { type: "property", key: "name" }]
+ * parsePath("users[0].name") // [{ type: "property", key: "users" }, { type: "index", key: "0" }, { type: "property", key: "name" }]
+ * parsePath("data\\.file[1]", { escapeChar: "\\" }) // [{ type: "property", key: "data.file" }, { type: "index", key: "1" }]
+ */
+declare function parsePath(notation: string, options?: ParserOptions): PropertyPath;
+/**
+ * Creates an accessor function from a parsed property path with array support
+ * The returned function safely navigates nested objects and arrays using the parsed path
+ * @param path - Array of path segments to access in sequence
+ * @returns Function that takes a record and returns the nested value or undefined
+ * @example
+ * const path = [{ type: "property", key: "users" }, { type: "index", key: "0" }, { type: "property", key: "name" }];
+ * const accessor = createAccessorFromPath(path);
+ * accessor({ users: [{ name: "John" }] }) // "John"
+ */
+declare function createAccessorFromPath<T = unknown>(path: PropertyPath): PropertyAccessor<T>;
+/**
+ * Main parser function that creates an accessor from notation string with array support
+ * Combines path parsing and accessor creation into a single operation
+ * @param notation - Notation string with dots and brackets (e.g., "users[0].profile.name")
+ * @param options - Parser configuration options
+ * @returns Accessor function for the specified property path
+ * @example
+ * const accessor = createAccessor("user.profile.name");
+ * const name = accessor(userData); // safely gets nested property
+ *
+ * const arrayAccessor = createAccessor("users[0].name");
+ * const userName = arrayAccessor(data); // safely accesses array elements
+ *
+ * const complexAccessor = createAccessor("items[2].meta\\.data.values[1]", { escapeChar: "\\" });
+ * const value = complexAccessor(response); // handles escaped dots and nested arrays
+ */
+declare function createAccessor<T = unknown>(notation: string, options?: ParserOptions): PropertyAccessor<T>;
+/**
+ * Utility function to test if a property path exists in a record (with array support)
+ * Useful for validation before attempting to access nested properties or array elements
+ * @param notation - Notation string with dots and brackets to test
+ * @param record - Record to test against
+ * @param options - Parser configuration options
+ * @returns Boolean indicating if the complete path exists
+ * @example
+ * hasProperty("user.name", data) // true if data.user.name exists
+ * hasProperty("users[0].name", data) // true if data.users[0].name exists
+ * hasProperty("missing.path", data) // false if any part is undefined
+ */
+declare function hasProperty(notation: string, record: Record<string, any>, options?: ParserOptions): boolean;
+export { createAccessor, createAccessorFromPath, parsePath, hasProperty, type PropertyAccessor, type PropertyPath, type PathSegment, type ParserOptions, };

package/dist/lib/templates/parseTemplate.d.ts

@@ -0,0 +1,6 @@
+import { PipeRegistry } from "../pipes";
+export type RenderTemplate = (data: Record<string, any>, component?: any) => string;
+export interface TemplateParserOptions {
+    pipeRegistry?: PipeRegistry;
+}
+export declare function compileMustard(template: string, options?: TemplateParserOptions): RenderTemplate;