@relax.js/core 1.0.0

package/dist/lib/collections/Pager.d.ts

@@ -0,0 +1,15 @@
+export declare class PageSelectedEvent extends CustomEvent<number> {
+    page: number;
+    constructor(page: number);
+}
+export declare class Pager {
+    private container;
+    private totalCount;
+    private pageSize;
+    private currentPage;
+    constructor(container: HTMLElement, totalCount: number, pageSize: number);
+    private render;
+    private selectPage;
+    update(totalCount: number): void;
+    getCurrentPage(): number;
+}

package/dist/lib/collections/TableRenderer.d.ts

@@ -0,0 +1,44 @@
+export declare class TableRenderer {
+    private table;
+    private template;
+    private component;
+    private dataMap;
+    private rowMap;
+    IdColumn: string;
+    constructor(table: HTMLTableElement, template: HTMLTemplateElement, idColumn: string, component: HTMLElement);
+    render(data: Record<string, any>[]): void;
+    private clearRows;
+    private renderRow;
+    private populateRow;
+    private attachEventHandlers;
+    update(data: Record<string, any>): void;
+}
+export declare class SortChangeEvent extends CustomEvent<SortColumn[]> {
+    constructor(sortColumns: SortColumn[]);
+}
+type SortDirection = 'asc' | 'desc';
+export type SortColumn = {
+    column: string;
+    direction: SortDirection;
+};
+export declare class TableSorter {
+    private table;
+    private sortColumns;
+    private component;
+    constructor(table: HTMLTableElement, component: HTMLElement);
+    private setupListeners;
+    private toggle;
+    private emit;
+    private updateSortIndicators;
+    getSortColumns(): SortColumn[];
+    clear(): void;
+}
+declare global {
+    interface HTMLTableElementEventMap extends HTMLElementEventMap {
+        'sortchange': SortChangeEvent;
+    }
+    interface HTMLTableElement {
+        addEventListener<K extends keyof HTMLTableElementEventMap>(type: K, listener: (this: HTMLTableElement, ev: HTMLTableElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+    }
+}
+export {};

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

@@ -0,0 +1 @@
+export * from '../DependencyInjection';

package/dist/lib/elements/CopyAttributes.d.ts

@@ -0,0 +1,2 @@
+export declare function copyInputAttributes(source: HTMLElement, target: HTMLInputElement | HTMLTextAreaElement): boolean;
+export declare function copyAttributes(source: HTMLElement, target: HTMLElement, attributes: string[]): boolean;

package/dist/lib/elements/dom.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Finds exactly one element matching the selector. When the selector starts
+ * with `#`, both `id` and `name` attributes are tried.
+ *
+ * @example
+ *     const input = selectOne<HTMLInputElement>('#email');
+ *     const btn = selectOne<HTMLButtonElement>('.submit', form);
+ */
+export declare function selectOne<T extends Element = HTMLElement>(selector: string, parent?: Element | Document): T;
+/**
+ * Sets a validation error on a form field found by selector. Supports native
+ * form elements and form-associated custom elements using `ElementInternals`.
+ *
+ * @example
+ *     formError('#email', 'Please enter a valid email');
+ *     formError('#email', ''); // clears the error
+ */
+export declare function formError(selector: string, message: string, parent?: Element | Document): void;

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

@@ -0,0 +1,2 @@
+export { selectOne, formError } from './dom';
+export { getParentComponent } from '../getParentComponent';

package/dist/lib/errors.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Global error handling for Relaxjs.
+ * Register a handler with `onError()` to intercept errors before they throw.
+ * Call `ctx.suppress()` in the handler to prevent the error from being thrown.
+ *
+ * @example
+ * import { onError } from 'relaxjs';
+ *
+ * onError((error, ctx) => {
+ *     logToService(error.message, error.context);
+ *     showToast(error.message);
+ *     ctx.suppress();
+ * });
+ */
+/**
+ * Passed to error handlers to control error behavior.
+ * Call `suppress()` to prevent the error from being thrown.
+ */
+export interface ErrorContext {
+    suppress(): void;
+}
+/**
+ * Error with structured context for debugging.
+ * The `context` record contains details like route name, component tag, route data.
+ *
+ * @example
+ * onError((error, ctx) => {
+ *     console.log(error.context.route);
+ *     console.log(error.context.componentTagName);
+ * });
+ */
+export declare class RelaxError extends Error {
+    context: Record<string, unknown>;
+    constructor(message: string, context: Record<string, unknown>);
+}
+type ErrorHandler = (error: RelaxError, ctx: ErrorContext) => void;
+/**
+ * Registers a global error handler for Relaxjs errors.
+ * The handler receives the error and an `ErrorContext`.
+ * Call `ctx.suppress()` to prevent the error from being thrown.
+ * Only one handler can be active at a time; subsequent calls replace the previous handler.
+ *
+ * @example
+ * onError((error, ctx) => {
+ *     if (error.context.route === 'optional-panel') {
+ *         ctx.suppress();
+ *         return;
+ *     }
+ *     showErrorDialog(error.message);
+ * });
+ */
+export declare function onError(fn: ErrorHandler): void;
+/**
+ * Reports an error through the global handler.
+ * Returns the `RelaxError` if it should be thrown, or `null` if the handler suppressed it.
+ * The caller is responsible for throwing the returned error.
+ *
+ * @param message - Human-readable error description
+ * @param context - Structured data for debugging (route, component, params, cause, etc.)
+ * @returns The error to throw, or `null` if suppressed
+ *
+ * @example
+ * const error = reportError('Failed to load route component', {
+ *     route: 'user',
+ *     componentTagName: 'user-profile',
+ *     routeData: { id: 123 },
+ * });
+ * if (error) throw error;
+ */
+export declare function reportError(message: string, context: Record<string, unknown>): RelaxError | null;
+export {};

package/dist/lib/forms/FormReader.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @module FormReader
+ * Utilities for reading form data into typed objects.
+ * Handles type conversion based on input types and data-type attributes.
+ *
+ * @example
+ * // Basic form reading
+ * const form = document.querySelector('form');
+ * const data = readData(form);
+ *
+ * // Type-safe mapping to a class instance
+ * const user = mapFormToClass(form, new UserDTO());
+ */
+/**
+ * Maps form field values to a class instance's properties.
+ * Automatically converts values based on input types (checkbox, number, date).
+ *
+ * Form field names must match property names on the target instance.
+ *
+ * @template T - The type of the class instance
+ * @param form - The HTML form element to read from
+ * @param instance - The class instance to populate
+ * @param options - Configuration options
+ * @param options.throwOnMissingProperty - Throw if form field has no matching property
+ * @param options.throwOnMissingField - Throw if class property has no matching form field
+ * @returns The populated instance
+ *
+ * @example
+ * class UserDTO {
+ *     name: string = '';
+ *     email: string = '';
+ *     age: number = 0;
+ *     newsletter: boolean = false;
+ * }
+ *
+ * const form = document.querySelector('form');
+ * const user = mapFormToClass(form, new UserDTO());
+ * console.log(user.name, user.age, user.newsletter);
+ *
+ * @example
+ * // With validation
+ * const user = mapFormToClass(form, new UserDTO(), {
+ *     throwOnMissingProperty: true,  // Catch typos in form field names
+ *     throwOnMissingField: true      // Ensure all DTO fields are in form
+ * });
+ */
+export declare function mapFormToClass<T extends object>(form: HTMLFormElement, instance: T, options?: {
+    throwOnMissingProperty?: boolean;
+    throwOnMissingField?: boolean;
+}): T;
+/**
+ * Configuration options for form reading operations.
+ */
+export interface FormReaderOptions {
+    /** Prefix to strip from field names when mapping to properties */
+    prefix?: string;
+    /** If true, checkboxes return their value instead of true/false */
+    disableBinaryCheckbox?: boolean;
+    /** If true, radio buttons return their value instead of true/false */
+    disableBinaryRadioButton?: boolean;
+}
+/**
+ * Gets the appropriate type converter function for a form element.
+ * Uses the `data-type` attribute if present, otherwise infers from input type.
+ *
+ * @param element - The form element to get a converter for
+ * @returns A function that converts string values to the appropriate type
+ *
+ * @example
+ * // With data-type attribute
+ * <input name="age" data-type="number" />
+ * const converter = getDataConverter(input);
+ * converter('42'); // Returns: 42 (number)
+ *
+ * @example
+ * // Inferred from input type
+ * <input type="checkbox" name="active" />
+ * const converter = getDataConverter(checkbox);
+ * converter('true'); // Returns: true (boolean)
+ */
+export declare function getDataConverter(element: HTMLElement): ConverterFunc;
+/**
+ * Reads all form data into a plain object with automatic type conversion.
+ * Handles multiple values (e.g., multi-select) and custom form-associated elements.
+ *
+ * Type conversion is based on:
+ * 1. `data-type` attribute if present (number, boolean, string, Date)
+ * 2. Input type (checkbox, number, date, etc.)
+ * 3. Falls back to string
+ *
+ * @param form - The HTML form element to read
+ * @returns Object with property names matching field names
+ *
+ * @example
+ * // HTML form
+ * <form>
+ *     <input name="username" value="john" />
+ *     <input name="age" type="number" value="25" />
+ *     <input name="active" type="checkbox" checked />
+ *     <select name="colors" multiple>
+ *         <option value="red" selected>Red</option>
+ *         <option value="blue" selected>Blue</option>
+ *     </select>
+ * </form>
+ *
+ * // Reading the form
+ * const data = readData(form);
+ * // Returns: { username: 'john', age: 25, active: true, colors: ['red', 'blue'] }
+ *
+ * @example
+ * // With custom form elements
+ * <form>
+ *     <r-input name="email" value="test@example.com" />
+ *     <r-checkbox name="terms" checked />
+ * </form>
+ * const data = readData(form);
+ 1*/
+export declare function readData<T = Record<string, unknown>>(form: HTMLFormElement): T;
+/**
+ * Function type for converting string form values to typed values.
+ */
+export type ConverterFunc = (value: string) => unknown;
+/**
+ * Supported data-type attribute values for explicit type conversion.
+ */
+export type DataType = 'number' | 'boolean' | 'string' | 'Date';
+/**
+ * Supported HTML input types for automatic type inference.
+ */
+export type InputType = 'tel' | 'text' | 'checkbox' | 'radio' | 'number' | 'color' | 'date' | 'datetime-local' | 'month' | 'week' | 'time';
+/**
+ * Converts string values to booleans.
+ * Handles 'true'/'false' strings and numeric values (>0 is true).
+ *
+ * @param value - String value to convert
+ * @returns Boolean value or undefined if empty
+ * @throws Error if value cannot be interpreted as boolean
+ */
+export declare function BooleanConverter(value?: string): boolean | undefined;
+/**
+ * Converts string values to numbers.
+ *
+ * @param value - String value to convert
+ * @returns Number value or undefined if empty
+ * @throws Error if value is not a valid number
+ */
+export declare function NumberConverter(value?: string): number | undefined;
+/**
+ * Converts string values to Date objects.
+ * Supports both ISO format (`2024-01-15`) and locale-specific formats
+ * (`01/15/2024` for en-US, `15.01.2024` for de, etc.) based on the
+ * current i18n locale.
+ *
+ * @param value - Date string in ISO or locale format
+ * @returns Date object
+ * @throws Error if value is not a valid date
+ *
+ * @example
+ * // ISO format (from <input type="date">)
+ * DateConverter('2024-01-15')   // Date(2024, 0, 15)
+ *
+ * // Locale format (from <input type="text" data-type="Date">)
+ * // with locale set to 'sv': 2024-01-15
+ * // with locale set to 'en-US': 01/15/2024
+ * // with locale set to 'de': 15.01.2024
+ */
+export declare function DateConverter(value: string): Date | undefined;
+/**
+ * Creates a converter function based on the data-type attribute value.
+ *
+ * @param dataType - The data-type attribute value
+ * @returns Appropriate converter function for the type
+ */
+export declare function createConverterFromDataType(dataType: DataType): ConverterFunc;
+/**
+ * Creates a converter function based on HTML input type.
+ * Handles special types like checkbox, date, time, week, and month.
+ *
+ * @param inputType - The HTML input type attribute value
+ * @returns Appropriate converter function for the type
+ */
+export declare function createConverterFromInputType(inputType: InputType): ConverterFunc;

package/dist/lib/forms/FormValidator.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @module FormValidator
+ * Form validation with support for native HTML5 validation and error summaries.
+ * Provides automatic validation on submit with customizable behavior.
+ *
+ * @example
+ * // Basic usage with submit callback
+ * const form = document.querySelector('form');
+ * const validator = new FormValidator(form, {
+ *     submitCallback: () => saveData()
+ * });
+ *
+ * @example
+ * // With auto-validation on input
+ * const validator = new FormValidator(form, {
+ *     autoValidate: true,
+ *     useSummary: true
+ * });
+ */
+/**
+ * Configuration options for FormValidator.
+ */
+export interface ValidatorOptions {
+    /** Validate on every input event, not just submit */
+    autoValidate?: boolean;
+    /** Show errors in a summary element instead of browser tooltips */
+    useSummary?: boolean;
+    /** Custom validation function called before native validation */
+    customChecks?: (form: HTMLFormElement) => void;
+    /** Always prevent default form submission */
+    preventDefault?: boolean;
+    /** Prevent default on validation failure (default: true) */
+    preventDefaultOnFailed?: boolean;
+    /** Callback invoked when form passes validation */
+    submitCallback?: () => void;
+}
+/**
+ * Form validation helper that integrates with HTML5 validation.
+ * Supports error summaries, auto-validation, and custom submit handling.
+ *
+ * @example
+ * // Prevent submission and handle manually
+ * class MyComponent extends HTMLElement {
+ *     private validator: FormValidator;
+ *
+ *     connectedCallback() {
+ *         const form = this.querySelector('form');
+ *         this.validator = new FormValidator(form, {
+ *             submitCallback: () => this.handleSubmit()
+ *         });
+ *     }
+ *
+ *     private async handleSubmit() {
+ *         const data = readData(this.form);
+ *         await fetch('/api/save', { method: 'POST', body: JSON.stringify(data) });
+ *     }
+ * }
+ *
+ * @example
+ * // With error summary display
+ * const validator = new FormValidator(form, {
+ *     useSummary: true,
+ *     autoValidate: true
+ * });
+ */
+export declare class FormValidator {
+    private form;
+    private options?;
+    private errorSummary;
+    constructor(form: HTMLFormElement, options?: ValidatorOptions);
+    /**
+     * Validates all form fields.
+     * Uses native HTML5 validation and optionally displays an error summary.
+     *
+     * @returns true if form is valid, false otherwise
+     */
+    validateForm(): boolean;
+    /**
+     * Displays a list of error messages in the summary element.
+     *
+     * @param messages - Array of error messages to display
+     */
+    displayErrorSummary(messages: string[]): void;
+    private createErrorSummary;
+    /**
+     * Adds a single error to the summary display.
+     *
+     * @param fieldName - The name of the field with the error
+     * @param message - The error message
+     */
+    addErrorToSummary(fieldName: string, message: string): void;
+    /**
+     * Clears all errors from the summary display.
+     */
+    clearErrorSummary(): void;
+    private focusFirstErrorElement;
+    /**
+     * Finds a form element relative to the given element.
+     * Searches parent first, then direct children.
+     *
+     * @param element - The element to search from
+     * @returns The found form element
+     * @throws Error if no form is found
+     *
+     * @example
+     * class MyComponent extends HTMLElement {
+     *     connectedCallback() {
+     *         const form = FormValidator.FindForm(this);
+     *         new FormValidator(form);
+     *     }
+     * }
+     */
+    static FindForm(element: HTMLElement): HTMLFormElement;
+}

package/dist/lib/forms/ValidationRules.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @module ValidationRules
+ * Form validation rules for use with FormValidator.
+ * Provides declarative validation through decorators.
+ *
+ * Validation messages use the i18n system. Load the 'r-validation' namespace
+ * for localized error messages:
+ *
+ * @example
+ * await loadNamespace('r-validation');
+ *
+ * @example
+ * // In HTML, use validation attributes
+ * <input name="age" data-validate="required range(0-120)" />
+ */
+/**
+ * Context provided to validators during validation.
+ */
+export interface ValidationContext {
+    /** The HTML input type (text, number, email, etc.) */
+    inputType: string;
+    /** The data-type attribute value if present */
+    dataType?: string;
+    /** Adds an error message to the validation result */
+    addError(message: string): void;
+}
+/**
+ * Interface for custom validators.
+ */
+interface Validator {
+    /**
+     * Validates the given value.
+     * @param value - The string value to validate
+     * @param context - Validation context with type info and error reporting
+     */
+    validate(value: string, context: ValidationContext): void;
+}
+interface ValidatorRegistryEntry {
+    validator: {
+        new (): Validator;
+    };
+    validInputTypes: string[];
+}
+/**
+ * Decorator to register a validator class for a specific validation name.
+ *
+ * @param validationName - The name used in data-validate attribute
+ * @param validInputTypes - Optional list of input types this validator applies to
+ *
+ * @example
+ * @RegisterValidator('email')
+ * class EmailValidation implements Validator {
+ *     validate(value: string, context: ValidationContext) {
+ *         if (!value.includes('@')) {
+ *             context.addError('Invalid email address');
+ *         }
+ *     }
+ * }
+ */
+export declare function RegisterValidator(validationName: string, validInputTypes?: string[]): (target: {
+    new (...args: unknown[]): Validator;
+}) => void;
+/**
+ * Looks up a registered validator by name.
+ *
+ * @param name - The validator name used in `data-validate`
+ * @returns The registry entry, or `undefined` if not found
+ */
+export declare function getValidator(name: string): ValidatorRegistryEntry | undefined;
+/**
+ * Validates that a field has a non-empty value.
+ * Use with `data-validate="required"`.
+ */
+export declare class RequiredValidation implements Validator {
+    static create(rule: string): RequiredValidation | null;
+    validate(value: string, context: ValidationContext): void;
+    getMessage(): string;
+}
+/**
+ * Validates that a numeric value falls within a specified range.
+ * Use with `data-validate="range(min-max)"`.
+ *
+ * @example
+ * <input name="age" type="number" data-validate="range(0-120)" />
+ */
+export declare class RangeValidation implements Validator {
+    min: number;
+    max: number;
+    constructor(min: number, max: number);
+    static create(rule: string): RangeValidation | null;
+    validate(value: string, context: ValidationContext): void;
+    getMessage(actual: string): string;
+}
+/**
+ * Validates that a value contains only numeric digits (0-9).
+ * Use with `data-validate="digits"`.
+ */
+export declare class DigitsValidation implements Validator {
+    static create(rule: string): DigitsValidation | null;
+    validate(value: string, context: ValidationContext): void;
+    getMessage(): string;
+}
+export {};

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

@@ -0,0 +1,4 @@
+export { FormReaderOptions, ConverterFunc, DataType, InputType, mapFormToClass, getDataConverter, readData, BooleanConverter, NumberConverter, DateConverter, createConverterFromDataType, createConverterFromInputType } from './FormReader';
+export { ValidatorOptions, FormValidator } from './FormValidator';
+export { setFormData } from './setFormData';
+export { ValidationContext, RegisterValidator, getValidator, RequiredValidation, RangeValidation, DigitsValidation } from './ValidationRules';

package/dist/lib/forms/setFormData.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Sets form field values from a data object using the name attribute.
+ * Supports dot notation for accessing nested properties and array handling.
+ *
+ * @param form - The HTML form element to populate
+ * @param data - The data object containing values to set in the form
+ *
+ * @example
+ * // Basic usage with flat object
+ * const form = document.querySelector('form');
+ * const data = { name: 'John', email: 'john@example.com' };
+ * setFormData(form, data);
+ *
+ * @example
+ * // Using with nested objects via dot notation
+ * const form = document.querySelector('form');
+ * const data = {
+ *   user: {
+ *     name: 'John',
+ *     contact: {
+ *       email: 'john@example.com'
+ *     }
+ *   }
+ * };
+ * // Form has fields with names like "user.name" and "user.contact.email"
+ * setFormData(form, data);
+ *
+ * @example
+ * // Using with simple arrays using [] notation
+ * const form = document.querySelector('form');
+ * const data = {
+ *   hobbies: ['Reading', 'Cycling', 'Cooking']
+ * };
+ * // Form has multiple fields with names like "hobbies[]"
+ * setFormData(form, data);
+ *
+ * @example
+ * // Using with array of objects using numeric indexers
+ * const form = document.querySelector('form');
+ * const data = {
+ *   users: [
+ *     { name: 'John', email: 'john@example.com' },
+ *     { name: 'Jane', email: 'jane@example.com' }
+ *   ]
+ * };
+ * // Form has fields with names like "users[0].name", "users[1].email", etc.
+ * setFormData(form, data);
+ */
+export declare function setFormData(form: HTMLFormElement, data: object): void;

package/dist/lib/getParentComponent.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Finds the closest parent element of a specific Web Component type.
+ * Traverses up the DOM tree looking for an ancestor matching the constructor.
+ *
+ * Useful for child components that need to communicate with or access
+ * their parent container component, common in composite component patterns.
+ *
+ * @template T - The type of HTMLElement to find
+ * @param node - The starting node to search from
+ * @param constructor - The class constructor of the desired element type
+ * @returns The matching parent element or null if not found
+ *
+ * @example
+ * // Inside a child component, find the parent container
+ * class ListItem extends HTMLElement {
+ *     connectedCallback() {
+ *         const list = getParentComponent(this, ListContainer);
+ *         if (list) {
+ *             list.registerItem(this);
+ *         }
+ *     }
+ * }
+ *
+ * @example
+ * // Access parent component's methods
+ * class TabPanel extends HTMLElement {
+ *     activate() {
+ *         const tabs = getParentComponent(this, TabContainer);
+ *         tabs?.selectPanel(this);
+ *     }
+ * }
+ *
+ * @example
+ * // Handle case where parent might not exist
+ * const form = getParentComponent(input, FormContainer);
+ * if (!form) {
+ *     console.warn('Input must be inside a FormContainer');
+ *     return;
+ * }
+ */
+export declare function getParentComponent<T extends HTMLElement>(node: Node, constructor: {
+    new (...args: any[]): T;
+}): T | null;