@relax.js/core 1.0.0

package/dist/lib/http/ServerSentEvents.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @module ServerSentEvents
+ * SSE client that dispatches received events as DOM events.
+ * Uses the browser's built-in EventSource reconnection.
+ *
+ * @example
+ * const sse = new SSEClient('/api/events', {
+ *     eventTypes: ['user-updated', 'order-created']
+ * });
+ * sse.connect();
+ *
+ * document.addEventListener('user-updated', (e: SSEDataEvent) => {
+ *     console.log('User updated:', e.data);
+ * });
+ */
+/**
+ * Event dispatched when an SSE message is received.
+ * The event name matches the SSE event type.
+ */
+export declare class SSEDataEvent extends Event {
+    data: unknown;
+    constructor(eventName: string, data: unknown, eventInit?: EventInit);
+}
+/**
+ * Factory function for creating custom event instances.
+ *
+ * @example
+ * const factory: SSEEventFactory = (eventName, data) => {
+ *     switch (eventName) {
+ *         case 'user-updated':
+ *             return new UserUpdatedEvent(data as User);
+ *         default:
+ *             return new SSEDataEvent(eventName, data);
+ *     }
+ * };
+ */
+export type SSEEventFactory = (eventName: string, data: unknown) => Event;
+/**
+ * Configuration options for SSEClient.
+ */
+export interface SSEOptions {
+    /**
+     * Target element or CSS selector for event dispatching.
+     * Defaults to document.
+     */
+    target?: string | Element;
+    /**
+     * Whether to send credentials with the request (default: false).
+     */
+    withCredentials?: boolean;
+    /**
+     * Specific SSE event types to listen for.
+     * If not specified, listens to the default 'message' event.
+     *
+     * @example
+     * eventTypes: ['user-updated', 'order-created']
+     */
+    eventTypes?: string[];
+    /**
+     * Factory function for creating custom event instances.
+     * If not provided, SSEDataEvent is used.
+     *
+     * @example
+     * eventFactory: (name, data) => new MyCustomEvent(name, data)
+     */
+    eventFactory?: SSEEventFactory;
+    /**
+     * Callback when connection is established.
+     */
+    onConnect?: (client: SSEClient) => void;
+    /**
+     * Callback when an error occurs.
+     * Note: EventSource automatically reconnects on errors.
+     */
+    onError?: (client: SSEClient, error: Event) => void;
+}
+/**
+ * Server-Sent Events client that dispatches received events as DOM events.
+ * Uses the browser's built-in EventSource with automatic reconnection.
+ *
+ * @example
+ * const sse = new SSEClient('/api/events', {
+ *     target: '#notifications',
+ *     eventTypes: ['notification', 'alert']
+ * });
+ *
+ * sse.connect();
+ *
+ * document.querySelector('#notifications')
+ *     .addEventListener('notification', (e: SSEDataEvent) => {
+ *         showNotification(e.data);
+ *     });
+ *
+ * sse.disconnect();
+ */
+export declare class SSEClient {
+    private url;
+    private options?;
+    private eventSource?;
+    private target;
+    /**
+     * Whether the client is currently connected.
+     */
+    get connected(): boolean;
+    constructor(url: string, options?: SSEOptions);
+    /**
+     * Establish connection to the SSE endpoint.
+     */
+    connect(): void;
+    /**
+     * Close the connection.
+     */
+    disconnect(): void;
+    private resolveTarget;
+    private dispatchEvent;
+}

package/dist/lib/http/SimpleWebSocket.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @module SimpleWebSocket
+ * WebSocket client with automatic reconnection and message queuing.
+ * Provides a reliable messaging layer over WebSocket connections.
+ *
+ * @example
+ * // Create and connect
+ * const ws = new WebSocketClient<ChatMessage>('wss://chat.example.com');
+ * ws.connect();
+ *
+ * // Send and receive
+ * await ws.send({ text: 'Hello' });
+ * const msg = await ws.receive();
+ */
+/**
+ * Simplified message event for WebSocket data.
+ */
+export interface SimpleDataEvent {
+    data: string | ArrayBufferLike | Blob | ArrayBufferView;
+}
+/**
+ * Abstraction interface for WebSocket to enable unit testing.
+ * Implement this for custom WebSocket instances or mocks.
+ */
+export interface WebSocketAbstraction {
+    onopen: ((event: Event) => void) | null;
+    onerror: ((event: ErrorEvent) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onmessage: ((event: SimpleDataEvent) => void) | null;
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(): void;
+}
+/**
+ * Factory function type for creating WebSocket instances.
+ */
+export type WebSocketFactory = () => WebSocketAbstraction;
+/**
+ * Managed WebSocket client with automatic reconnection and message queuing.
+ *
+ * Features:
+ * - Automatic reconnection on disconnect
+ * - Message queuing when disconnected
+ * - Type-safe message handling with optional codecs
+ * - Promise-based receive API
+ *
+ * @template TMessage - The type of messages sent and received
+ *
+ * @example
+ * // Basic usage
+ * interface ChatMessage { user: string; text: string; }
+ *
+ * const client = new WebSocketClient<ChatMessage>('wss://chat.example.com');
+ * client.connect();
+ *
+ * // Send messages
+ * await client.send({ user: 'John', text: 'Hello!' });
+ *
+ * // Receive messages
+ * while (true) {
+ *     const message = await client.receive();
+ *     console.log(`${message.user}: ${message.text}`);
+ * }
+ *
+ * @example
+ * // With options
+ * const client = new WebSocketClient<Message>('wss://api.example.com', {
+ *     autoReconnect: true,
+ *     onConnect: (socket) => console.log('Connected'),
+ *     onClose: () => console.log('Disconnected')
+ * });
+ */
+export declare class WebSocketClient<TMessage> {
+    private options?;
+    private ws?;
+    private receiveQueue;
+    private receivePromiseWrapper?;
+    private sendQueue;
+    private _isConnected;
+    private isSendingQueue;
+    private url?;
+    private wsFactory?;
+    private reconnectAttempts;
+    private shouldReconnect;
+    get connected(): boolean;
+    constructor(urlOrWebSocketFactory: string | WebSocketFactory, options?: WebSocketOptions<TMessage>);
+    connect(): void;
+    disconnect(): void;
+    send(data: TMessage): void;
+    /**
+     * Receive a new message.
+     *
+     * @throws Error if called while another receive() is pending.
+     * @throws Error if connection closes while waiting.
+     */
+    receive(): Promise<TMessage>;
+    private onMessage;
+    private reConnect;
+    private sendInternal;
+    private sendQueueItems;
+}
+/**
+ * CODEC used for messages.
+ */
+export interface WebSocketCodec<TMessage> {
+    /**
+     *
+     * @param data
+     */
+    encode(data: TMessage): string | ArrayBufferLike | Blob | ArrayBufferView;
+    /**
+     *
+     * @param data
+     */
+    decode(data: string | ArrayBufferLike | Blob | ArrayBufferView): TMessage;
+}
+/**
+ * Configuration options for @see WebSocketClient.
+ */
+export interface WebSocketOptions<TMessage> {
+    /**
+     * CODEC to use for inbound and outbound messages (if something else that JSON should be used).
+     */
+    codec?: WebSocketCodec<TMessage>;
+    /**
+     * Automatically reconnect when getting disconnected (default: true).
+     */
+    autoReconnect?: boolean;
+    /**
+     * Initial delay in milliseconds before reconnecting (default: 1000).
+     * Uses exponential backoff on subsequent attempts.
+     */
+    reconnectDelay?: number;
+    /**
+     * Maximum delay in milliseconds between reconnect attempts (default: 30000).
+     */
+    maxReconnectDelay?: number;
+    /**
+     * Callback when the WS is connected.
+     *
+     * Can be used for authentication messages etc.
+     *
+     * @param socket Socket
+     */
+    onConnect?: (socket: WebSocketClient<TMessage>) => void;
+    /**
+     * Invoked when the connection is closed.
+     *
+     * The connection will be automatically reconnected if configured (on by default).
+     *
+     * @param socket Socket.
+     */
+    onClose?: (socket: WebSocketClient<TMessage>) => void;
+}

package/dist/lib/http/http.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @module http
+ * Type-safe HTTP module built on fetch() with automatic JWT handling.
+ *
+ * @example
+ * import { configure, get, post } from './http';
+ *
+ * configure({ baseUrl: '/api' });
+ * const response = await get('/users');
+ * const users = response.as<User[]>();
+ */
+/**
+ * Configuration options for the http module.
+ */
+export interface HttpOptions {
+    /**
+     * Root URL to remote endpoint. Used so that each method only has to specify path in requests.
+     */
+    baseUrl?: string;
+    /**
+     * Default content type to use if none is specified in the request method.
+     */
+    contentType?: string;
+    /**
+     * Checks for a JWT token in localStorage to automatically include it in requests.
+     *
+     * Undefined = use "jwt", null = disable.
+     */
+    bearerTokenName?: string | null;
+    /**
+     * Default request timeout in milliseconds.
+     * Uses `AbortSignal.timeout()` to automatically abort requests that take too long.
+     * Can be overridden per-request by passing a `signal` in `RequestInit`.
+     *
+     * @example
+     * configure({ baseUrl: '/api', timeout: 10000 }); // 10 second timeout
+     */
+    timeout?: number;
+}
+/**
+ * Response for request methods.
+ */
+export interface HttpResponse {
+    /**
+     * Http status code.
+     */
+    statusCode: number;
+    /**
+     * Reason to why the status code was used.
+     */
+    statusReason: string;
+    /**
+     * True if this is a 2xx response.
+     */
+    success: boolean;
+    /**
+     * Content type of response body.
+     */
+    contentType: string | null;
+    /**
+     * Body returned.
+     *
+     * Body has been read and deserialized from json (if the request content type was 'application/json' which is the default).
+     */
+    body: unknown;
+    /**
+     * Charset used in body.
+     */
+    charset: string | null;
+    /**
+     * Cast body to a type.
+     */
+    as<T>(): T;
+}
+/**
+ * Error thrown when a request fails.
+ */
+export declare class HttpError extends Error {
+    message: string;
+    response: HttpResponse;
+    constructor(response: HttpResponse);
+}
+/**
+ * HTTP request options.
+ */
+export interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    mode?: 'cors' | 'no-cors' | '*cors' | 'same-origin';
+    cache: 'default' | 'no-store' | 'reload' | 'no-cache' | 'force-cache' | 'only-if-cached';
+    credentials: 'omit' | 'same-origin' | 'include';
+    headers: Map<string, string>;
+    redirect: 'follow' | 'manual' | '*follow' | 'error';
+    referrerPolicy: 'no-referrer' | '*no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url';
+    /**
+     * Will be serialized if the content type is json (and the body is an object).
+     */
+    body: unknown;
+}
+declare type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Replace the fetch implementation for testing purposes.
+ *
+ * @param fn - Custom fetch function, or undefined to restore the default.
+ *
+ * @example
+ * setFetch(async (url, options) => {
+ *     return new Response(JSON.stringify({ id: 1 }), { status: 200 });
+ * });
+ */
+export declare function setFetch(fn?: FetchFn): void;
+/**
+ * Configure the http module.
+ *
+ * @example
+ * configure({ baseUrl: '/api/v1', bearerTokenName: 'auth_token' });
+ */
+export declare function configure(options: HttpOptions): void;
+/**
+ * Make an HTTP request.
+ *
+ * @param url - URL to make the request against.
+ * @param options - Request options.
+ * @returns Response from server.
+ *
+ * @example
+ * const response = await request('/users', { method: 'GET' });
+ */
+export declare function request(url: string, options?: RequestInit): Promise<HttpResponse>;
+/**
+ * GET a resource.
+ *
+ * @param url - URL to get resource from.
+ * @param queryString - Optional query string parameters.
+ * @param options - Request options.
+ * @returns HTTP response.
+ *
+ * @example
+ * const response = await get('/users', { page: '1', limit: '10' });
+ * const users = response.as<User[]>();
+ */
+export declare function get(url: string, queryString?: Record<string, string>, options?: RequestInit): Promise<HttpResponse>;
+/**
+ * POST a resource.
+ *
+ * @param url - URL to post to.
+ * @param data - Data to post.
+ * @param options - Request options.
+ * @returns HTTP response.
+ *
+ * @example
+ * const response = await post('/users', JSON.stringify({ name: 'John' }));
+ */
+export declare function post(url: string, data: BodyInit, options?: RequestInit): Promise<HttpResponse>;
+/**
+ * PUT a resource.
+ *
+ * @param url - URL to resource.
+ * @param data - Data to put.
+ * @param options - Request options.
+ * @returns HTTP response.
+ *
+ * @example
+ * const response = await put('/users/1', JSON.stringify({ name: 'Jane' }));
+ */
+export declare function put(url: string, data: BodyInit, options?: RequestInit): Promise<HttpResponse>;
+/**
+ * DELETE a resource.
+ *
+ * @param url - URL to resource.
+ * @param options - Request options.
+ * @returns HTTP response.
+ *
+ * @example
+ * const response = await del('/users/1');
+ */
+export declare function del(url: string, options?: RequestInit): Promise<HttpResponse>;
+export {};

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

@@ -0,0 +1,3 @@
+export { HttpOptions, HttpResponse, HttpError, RequestOptions, configure, setFetch, request, get, post, put, del } from './http';
+export { SSEDataEvent, SSEOptions, SSEEventFactory, SSEClient } from './ServerSentEvents';
+export { SimpleDataEvent, WebSocketAbstraction, WebSocketFactory, WebSocketClient, WebSocketCodec, WebSocketOptions } from './SimpleWebSocket';

package/dist/lib/i18n/i18n.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @module i18n
+ * Internationalization support with namespace-based translations.
+ * Uses ICU message format for pluralization, select, and formatting.
+ *
+ * @example
+ * // Initialize locale
+ * await setLocale('sv');
+ *
+ * // Use translations
+ * const greeting = t('r-common:greeting', { name: 'John' });
+ * const items = t('shop:items', { count: 5 });
+ */
+type Namespace = string;
+export type MissingTranslationHandler = (key: string, namespace: string, locale: string) => void;
+/**
+ * Dispatched on `document` after `setLocale()` completes.
+ * The `locale` property contains the new normalized locale code.
+ *
+ * @example
+ * document.addEventListener('localechange', (e) => {
+ *     console.log(`Locale changed to ${e.locale}`);
+ *     this.render();
+ * });
+ */
+export declare class LocaleChangeEvent extends Event {
+    readonly locale: string;
+    constructor(locale: string);
+}
+declare global {
+    interface DocumentEventMap {
+        localechange: LocaleChangeEvent;
+    }
+}
+/**
+ * Sets the current locale and loads the common namespace.
+ * Clears previously loaded translations and dispatches a `localechange` event.
+ *
+ * @param locale - The locale code (e.g., 'en', 'sv', 'en-US')
+ *
+ * @example
+ * await setLocale('sv');
+ */
+export declare function setLocale(locale: string): Promise<void>;
+/**
+ * Loads a translation namespace on demand.
+ * Falls back to the default locale if translations are not found.
+ *
+ * @param namespace - The namespace to load (e.g., 'shop', 'errors')
+ *
+ * @example
+ * await loadNamespace('shop');
+ * const price = t('shop:priceLabel');
+ */
+export declare function loadNamespace(namespace: Namespace): Promise<void>;
+/**
+ * Loads multiple translation namespaces in parallel.
+ *
+ * @param namespaces - Array of namespace names to load
+ *
+ * @example
+ * await loadNamespaces(['r-pipes', 'r-validation']);
+ */
+export declare function loadNamespaces(namespaces: Namespace[]): Promise<void>;
+/**
+ * Translates a key with optional value interpolation.
+ * Supports ICU message format for pluralization and select.
+ *
+ * @param fullKey - Translation key in format 'namespace:key' or just 'key' (uses 'r-common')
+ * @param values - Values to interpolate into the message
+ * @returns The translated string, or the key if not found
+ *
+ * @example
+ * // Simple translation
+ * t('greeting'); // Uses r-common:greeting
+ *
+ * // With namespace
+ * t('errors:notFound');
+ *
+ * // With interpolation
+ * t('welcome', { name: 'John' }); // "Welcome, John!"
+ *
+ * // With pluralization (ICU format)
+ * t('items', { count: 5 }); // "5 items" or "5 föremål"
+ */
+export declare function t(fullKey: string, values?: Record<string, any>): string;
+/**
+ * Returns the current locale code.
+ *
+ * @returns The normalized locale code (e.g., 'en', 'sv')
+ */
+export declare function getCurrentLocale(): string;
+/**
+ * Registers a handler called when `t()` encounters a missing translation key.
+ * Pass `null` to remove the handler.
+ *
+ * @param handler - Callback receiving the key, namespace, and locale
+ *
+ * @example
+ * onMissingTranslation((key, ns, locale) => {
+ *     console.warn(`Missing: ${ns}:${key} [${locale}]`);
+ * });
+ */
+export declare function onMissingTranslation(handler: MissingTranslationHandler | null): void;
+export {};

package/dist/lib/i18n/icu.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @module icu
+ * ICU message format support for internationalization.
+ * Provides pluralization, select, and value interpolation.
+ *
+ * @example
+ * // Simple interpolation
+ * formatICU('Hello, {name}!', { name: 'World' });
+ * // Returns: 'Hello, World!'
+ *
+ * @example
+ * // Pluralization
+ * formatICU('{count, plural, one {# item} other {# items}}', { count: 5 });
+ * // Returns: '5 items'
+ *
+ * @example
+ * // Select
+ * formatICU('{gender, select, male {He} female {She} other {They}}', { gender: 'female' });
+ * // Returns: 'She'
+ */
+/**
+ * Function type for message formatters.
+ * Implement this to provide custom message formatting.
+ */
+export type MessageFormatter = (message: string, values?: Record<string, any>, locale?: string) => string;
+/**
+ * Default ICU message formatter implementation.
+ * Supports simple interpolation, pluralization with exact matches, and select.
+ *
+ * @param message - ICU format message string
+ * @param values - Values to interpolate
+ * @param locale - Locale for plural rules (default: 'en')
+ * @returns Formatted message string
+ *
+ * @example
+ * defaultFormatICU('{n, plural, =0 {none} one {# item} other {# items}}', { n: 0 }, 'en');
+ * // Returns: 'none'
+ *
+ * @example
+ * defaultFormatICU('{role, select, admin {Full access} other {Limited access}}', { role: 'admin' });
+ * // Returns: 'Full access'
+ */
+export declare function defaultFormatICU(message: string, values: Record<string, any>, locale?: string): string;
+/**
+ * The active message formatter. Defaults to `defaultFormatICU`.
+ * Can be replaced with `setMessageFormatter` for custom formatting.
+ */
+export declare let formatICU: MessageFormatter;
+/**
+ * Replaces the default message formatter with a custom implementation.
+ * Use this to integrate with external i18n libraries like FormatJS.
+ *
+ * @param formatter - The custom formatter function
+ *
+ * @example
+ * // Use FormatJS IntlMessageFormat
+ * import { IntlMessageFormat } from 'intl-messageformat';
+ *
+ * setMessageFormatter((message, values, locale) => {
+ *     const fmt = new IntlMessageFormat(message, locale);
+ *     return fmt.format(values);
+ * });
+ */
+export declare function setMessageFormatter(formatter: MessageFormatter): void;

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

@@ -0,0 +1,2 @@
+export { t, setLocale, loadNamespace, loadNamespaces, getCurrentLocale, onMissingTranslation, LocaleChangeEvent, MissingTranslationHandler, } from './i18n';
+export { MessageFormatter, formatICU, setMessageFormatter, } from './icu';

package/dist/lib/index.d.ts

@@ -0,0 +1,16 @@
+export * from './errors';
+export * from './collections/Index';
+export * from './forms/FormValidator';
+export * from './forms/FormReader';
+export * from './forms/ValidationRules';
+export * from './forms/setFormData';
+export * from './html/index';
+export * from './routing';
+export * from "./DependencyInjection";
+export * from "./getParentComponent";
+export * from "./templates/NodeTemplate";
+export { generateSequentialId } from './SequentialId';
+export * from "./http/http";
+export * from "./http/ServerSentEvents";
+export * from './pipes';
+export * from './tools';

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

@@ -0,0 +1,52 @@
+import type { Route, RouteData } from './types';
+/**
+ * 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;
+    }
+}