@rokkit/forms 1.0.1 → 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jerry Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/src/display/index.d.ts

@@ -0,0 +1,5 @@
+export { default as DisplayValue } from "./DisplayValue.svelte";
+export { default as DisplaySection } from "./DisplaySection.svelte";
+export { default as DisplayTable } from "./DisplayTable.svelte";
+export { default as DisplayCardGrid } from "./DisplayCardGrid.svelte";
+export { default as DisplayList } from "./DisplayList.svelte";

package/dist/src/index.d.ts

@@ -0,0 +1,15 @@
+export { FormBuilder } from "./lib/builder.svelte.js";
+export { deriveSchemaFromValue } from "./lib/schema.js";
+export { deriveLayoutFromValue } from "./lib/layout.js";
+export { default as FormRenderer } from "./FormRenderer.svelte";
+export { default as Input } from "./Input.svelte";
+export { default as InputField } from "./InputField.svelte";
+export { default as InfoField } from "./InfoField.svelte";
+export { default as StatusList } from "./StatusList.svelte";
+export { default as StepIndicator } from "./StepIndicator.svelte";
+export * from "./display";
+export * from "./input";
+export { createLookup, createLookupManager, clearLookupCache } from "./lib/lookup.svelte.js";
+export { validateField, validateAll, createMessage, patterns } from "./lib/validation.js";
+export { defaultRenderers, resolveRenderer } from "./lib/renderers.js";
+export { getSchemaWithLayout, findAttributeByPath } from "./lib/fields.js";

package/dist/src/input/index.d.ts

@@ -0,0 +1,22 @@
+export { default as ArrayEditor } from "./ArrayEditor.svelte";
+export { default as InputCheckbox } from "./InputCheckbox.svelte";
+export { default as InputColor } from "./InputColor.svelte";
+export { default as InputDate } from "./InputDate.svelte";
+export { default as InputDateTime } from "./InputDateTime.svelte";
+export { default as InputEmail } from "./InputEmail.svelte";
+export { default as InputFile } from "./InputFile.svelte";
+export { default as InputMonth } from "./InputMonth.svelte";
+export { default as InputNumber } from "./InputNumber.svelte";
+export { default as InputPassword } from "./InputPassword.svelte";
+export { default as InputRadio } from "./InputRadio.svelte";
+export { default as InputRange } from "./InputRange.svelte";
+export { default as InputSelect } from "./InputSelect.svelte";
+export { default as InputSwatch } from "./InputSwatch.svelte";
+export { default as InputSwitch } from "./InputSwitch.svelte";
+export { default as InputTel } from "./InputTel.svelte";
+export { default as InputText } from "./InputText.svelte";
+export { default as InputTextArea } from "./InputTextArea.svelte";
+export { default as InputTime } from "./InputTime.svelte";
+export { default as InputToggle } from "./InputToggle.svelte";
+export { default as InputUrl } from "./InputUrl.svelte";
+export { default as InputWeek } from "./InputWeek.svelte";

package/dist/src/lib/builder.svelte.d.ts

@@ -0,0 +1,274 @@
+/**
+ * FormBuilder class for dynamically generating forms from data structures
+ */
+export class FormBuilder {
+    /**
+     * Create a new FormBuilder instance
+     * @param {Object} [data={}] - Initial data object
+     * @param {Object|null} [schema=null] - Optional schema override
+     * @param {Object|null} [layout=null] - Optional layout override
+     * @param {Object<string, import('./lookup.svelte.js').LookupConfig>} [lookups={}] - Lookup configurations
+     */
+    constructor(data?: Object, schema?: Object | null, layout?: Object | null, lookups?: {
+        [x: string]: import("./lookup.svelte.js").LookupConfig;
+    });
+    /** @type {FormElement[]} */
+    elements: FormElement[];
+    /** True when currentStep can advance to the next step */
+    canAdvance: boolean;
+    /** Combined schema+layout (scoped elements only) */
+    get combined(): any;
+    /**
+     * Set the data
+     * @param {Object} value - New data object
+     */
+    set data(value: Object);
+    /**
+     * Get the current data
+     * @returns {Object} Current data object
+     */
+    get data(): Object;
+    /**
+     * Set the schema
+     * @param {Object} value - New schema object
+     */
+    set schema(value: Object);
+    /**
+     * Get the current schema
+     * @returns {Object} Current schema object
+     */
+    get schema(): Object;
+    /**
+     * Set the layout
+     * @param {Object} value - New layout object
+     */
+    set layout(value: Object);
+    /**
+     * Get the current layout
+     * @returns {Object} Current layout object
+     */
+    get layout(): Object;
+    /**
+     * Set validation messages for fields
+     * @param {Object} value - Validation object with field paths as keys
+     */
+    set validation(value: Object);
+    /**
+     * Get the current validation state
+     * @returns {Object} Current validation object
+     */
+    get validation(): Object;
+    /**
+     * Get the lookup manager
+     * @returns {ReturnType<typeof createLookupManager>|null}
+     */
+    get lookupManager(): ReturnType<typeof createLookupManager> | null;
+    /**
+     * Configure lookups for the form
+     * @param {Object<string, import('./lookup.svelte.js').LookupConfig>} lookups - Lookup configurations
+     */
+    setLookups(lookups: {
+        [x: string]: import("./lookup.svelte.js").LookupConfig;
+    }): void;
+    /**
+     * Get lookup state for a field
+     * @param {string} fieldPath - Field path
+     * @returns {{ options: any[], loading: boolean, error: string|null, fields: Object, disabled: boolean }|null}
+     */
+    getLookupState(fieldPath: string): {
+        options: any[];
+        loading: boolean;
+        error: string | null;
+        fields: Object;
+        disabled: boolean;
+    } | null;
+    /**
+     * Check if a field is disabled due to unmet lookup dependencies
+     * @param {string} path - Field path
+     * @returns {boolean}
+     */
+    isFieldDisabled(path: string): boolean;
+    /**
+     * Manually refresh a field's lookup with the current form data
+     * @param {string} path - Field path
+     * @returns {Promise<void>}
+     */
+    refreshLookup(path: string): Promise<void>;
+    /**
+     * Check if a field has a lookup configured
+     * @param {string} fieldPath - Field path
+     * @returns {boolean}
+     */
+    hasLookup(fieldPath: string): boolean;
+    /**
+     * Initialize all lookups
+     * @returns {Promise<void>}
+     */
+    initializeLookups(): Promise<void>;
+    /**
+     * Update a specific field value
+     * @param {string} path - Field path (e.g., 'count', 'settings/distance')
+     * @param {any} value - New value
+     * @param {boolean} [triggerLookups=true] - Whether to trigger dependent lookups
+     */
+    updateField(path: string, value: any, triggerLookups?: boolean): void;
+    /**
+     * Get a field value by path
+     * @param {string} path - Field path
+     * @returns {any} Field value
+     */
+    getValue(path: string): any;
+    /**
+     * Set validation message for a specific field
+     * @param {string} fieldPath - Field path (without '#/' prefix)
+     * @param {Object|null} message - Validation message object or null to clear
+     * @param {string} message.state - Message state: 'error', 'warning', 'info', 'success'
+     * @param {string} message.text - Message text content
+     */
+    setFieldValidation(fieldPath: string, message: Object | null): void;
+    /**
+     * Clear all validation messages
+     */
+    clearValidation(): void;
+    /**
+     * Validate a single field by path
+     * @param {string} fieldPath - Field path (without '#/' prefix)
+     * @returns {import('./validation.js').ValidationMessage|null} Validation result
+     */
+    validateField(fieldPath: string): import("./validation.js").ValidationMessage | null;
+    /**
+     * Validate all fields, populate validation state
+     * @returns {Object} Validation results keyed by field path
+     */
+    validate(): Object;
+    /**
+     * Get form data with hidden field values stripped out
+     * Hidden fields are those absent from this.elements (the derived list)
+     * Does not mutate this.#data
+     * @returns {Object} Filtered data containing only visible field keys
+     */
+    getVisibleData(): Object;
+    /**
+     * Whether all fields pass validation (no error-state messages)
+     * @returns {boolean}
+     */
+    get isValid(): boolean;
+    /**
+     * Array of current error messages with paths
+     * @returns {Array<{path: string, state: string, text: string}>}
+     */
+    get errors(): Array<{
+        path: string;
+        state: string;
+        text: string;
+    }>;
+    /**
+     * Array of all validation messages with paths, ordered by severity
+     * @returns {Array<{path: string, state: string, text: string}>}
+     */
+    get messages(): Array<{
+        path: string;
+        state: string;
+        text: string;
+    }>;
+    /**
+     * Whether any field has been modified from its initial value
+     * @returns {boolean}
+     */
+    get isDirty(): boolean;
+    /**
+     * Set of field paths that differ from their initial values
+     * @returns {Set<string>}
+     */
+    get dirtyFields(): Set<string>;
+    /**
+     * Check if a single field has been modified from its initial value
+     * @param {string} fieldPath - Field path (without '#/' prefix)
+     * @returns {boolean}
+     */
+    isFieldDirty(fieldPath: string): boolean;
+    /**
+     * Update the initial data snapshot to the current data.
+     * Call after a successful save to clear dirty state.
+     */
+    snapshot(): void;
+    /**
+     * Reset form data to initial snapshot and clear validation
+     */
+    reset(): void;
+    /** True when the layout contains step elements */
+    get isMultiStep(): any;
+    /** Number of step elements in the layout */
+    get totalSteps(): any;
+    /** Zero-based index of the active step */
+    get currentStep(): number;
+    /**
+     * Validate the current step and advance if valid.
+     * @returns {boolean} true if advanced, false if validation failed
+     */
+    next(): boolean;
+    /**
+     * Move to the previous step without validation.
+     * @returns {boolean} true if moved, false if already on first step
+     */
+    prev(): boolean;
+    /**
+     * Navigate to a previously visited step (index < currentStep).
+     * @param {number} index - Target step index
+     */
+    goToStep(index: number): void;
+    /**
+     * Validate all fields in a given step. Defaults to currentStep.
+     * @param {number} [index] - Step index (defaults to currentStep)
+     * @returns {boolean} true if no errors
+     */
+    isStepValid(index?: number): boolean;
+    /**
+     * Validate all fields belonging to a step by index.
+     * @param {number} index - Step index
+     * @returns {boolean} true if no errors
+     */
+    validateStep(index: number): boolean;
+    #private;
+}
+export type FormElement = {
+    /**
+     * - JSON Pointer path (e.g., '#/email', '#/user/name')
+     */
+    scope: string;
+    /**
+     * - Input type (text, number, range, checkbox, select, etc.)
+     */
+    type: string;
+    /**
+     * - Current value from data
+     */
+    value: any;
+    /**
+     * - Whether to use custom child snippet (from layout)
+     */
+    override: boolean;
+    /**
+     * - Merged properties from schema + layout + validation
+     */
+    props: {
+        label?: string | undefined;
+        description?: string | undefined;
+        placeholder?: string | undefined;
+        required?: boolean | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        message?: {
+            /**
+             * - Message state: 'error', 'warning', 'info', 'success'
+             */
+            state?: string | undefined;
+            /**
+             * - Message text content
+             */
+            text?: string | undefined;
+        } | undefined;
+        dirty?: boolean | undefined;
+    };
+};
+import { createLookupManager } from './lookup.svelte.js';

package/dist/src/lib/conditions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Evaluate a showWhen condition against current form data.
+ * Returns true if the field should be shown (condition met or absent).
+ *
+ * @param {{ field: string, equals?: unknown, notEquals?: unknown } | null | undefined} condition
+ * @param {Record<string, unknown>} data - Top-level form data object
+ * @returns {boolean}
+ */
+export function evaluateCondition(condition: {
+    field: string;
+    equals?: unknown;
+    notEquals?: unknown;
+} | null | undefined, data: Record<string, unknown>): boolean;

package/dist/src/lib/conditions.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/fields.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Find an attribute in a schema by path
+ * @param {string} scope
+ * @param {import('../types').DataSchema} schema
+ * @returns {import('../types').LayoutSchema}
+ * @throws {Error} Invalid path
+ */
+export function findAttributeByPath(scope: string, schema: import("../types").DataSchema): import("../types").LayoutSchema;
+/**
+ * Get combined schema and layout
+ * @param {*} data
+ * @param {import('../types').DataSchema} schema
+ * @param {import('../types').LayoutSchema} layout
+ * @returns {import('../types').LayoutSchema}
+ */
+export function getSchemaWithLayout(schema: import("../types").DataSchema, layout: import("../types").LayoutSchema): import("../types").LayoutSchema;

package/dist/src/lib/fields.spec.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,8 @@
+export { FormBuilder } from "./builder.svelte.js";
+export { evaluateCondition } from "./conditions.js";
+export { default as FormRenderer } from "./FormRenderer.svelte";
+export { default as Input } from "./Input.svelte";
+export * from "./schema.js";
+export * from "./layout.js";
+export * from "./fields.js";
+export { validateField, validateAll, createMessage, patterns } from "./validation.js";

package/dist/src/lib/layout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Derives a layout from a given value.
+ * @param {any} value
+ * @param {string} scope
+ * @returns {import('../types').DataLayout}
+ */
+export function deriveLayoutFromValue(value: any, scope?: string): import("../types").DataLayout;

package/dist/src/lib/lookup.svelte.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Creates a lookup provider for a field
+ * @param {LookupConfig} config - Lookup configuration
+ * @returns {Object} Lookup provider with reactive state
+ */
+export function createLookup(config: LookupConfig): Object;
+/**
+ * Creates a lookup manager for a form with multiple lookups
+ * @param {Object<string, LookupConfig>} lookupConfigs - Map of field paths to lookup configs
+ * @returns {Object} Lookup manager
+ */
+export function createLookupManager(lookupConfigs: {
+    [x: string]: LookupConfig;
+}): Object;
+/**
+ * Clears the entire lookup cache
+ */
+export function clearLookupCache(): void;
+export type HookConfig = {
+    fetchHook: Function;
+    cacheKeyFn?: Function;
+    cacheTime: number;
+    transform?: Function;
+};
+export type UrlConfig = {
+    url: string;
+    cacheTime: number;
+    transform?: Function;
+};
+export type LookupApi = {
+    state: Object;
+    meta: Object;
+    fetch: Function;
+    clearCache: Function;
+    reset: Function;
+};
+export type LookupConfig = {
+    /**
+     * - URL template with optional placeholders (e.g., '/api/cities?country={country}')
+     */
+    url?: string | undefined;
+    /**
+     * - Async function replacing URL template
+     */
+    fetch?: ((formData: any) => Promise<any[]>) | undefined;
+    /**
+     * - Pre-loaded array for filter pattern
+     */
+    source?: any[] | undefined;
+    /**
+     * - Client-side filter applied to source
+     */
+    filter?: ((items: any[], formData: any) => any[]) | undefined;
+    /**
+     * - Custom cache key for fetch hooks (no caching when absent)
+     */
+    cacheKey?: ((formData: any) => string) | undefined;
+    /**
+     * - Field paths this lookup depends on
+     */
+    dependsOn?: string[] | undefined;
+    /**
+     * - Field mapping for the response data
+     */
+    fields?: Object | undefined;
+    /**
+     * - Cache duration in milliseconds (default: 5 minutes)
+     */
+    cacheTime?: number | undefined;
+    /**
+     * - Transform response data to options array
+     */
+    transform?: ((data: any) => any[]) | undefined;
+};
+export type LookupState = {
+    /**
+     * - Current options
+     */
+    options: any[];
+    /**
+     * - Whether lookup is in progress
+     */
+    loading: boolean;
+    /**
+     * - Error message if lookup failed
+     */
+    error: string | null;
+    /**
+     * - Whether field is disabled (deps not met)
+     */
+    disabled: boolean;
+};
+/**
+ * Cache entry structure
+ */
+export type CacheEntry = {
+    /**
+     * - Cached options
+     */
+    data: any[];
+    /**
+     * - When the cache was created
+     */
+    timestamp: number;
+};

package/dist/src/lib/renderers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolve a renderer component for a form element.
+ *
+ * Resolution order:
+ * 1. Explicit `renderer` name in element props → custom registry
+ * 2. Element type → registry lookup
+ * 3. Fallback → InputText
+ *
+ * @param {{ type: string, props?: { renderer?: string } }} element
+ * @param {Record<string, import('svelte').Component>} renderers - Merged registry
+ * @returns {import('svelte').Component}
+ */
+export function resolveRenderer(element: {
+    type: string;
+    props?: {
+        renderer?: string;
+    };
+}, renderers: Record<string, import("svelte").Component>): import("svelte").Component;
+/**
+ * Default renderer registry mapping type strings to components.
+ * @type {Record<string, import('svelte').Component>}
+ */
+export const defaultRenderers: Record<string, import("svelte").Component>;

package/dist/src/lib/schema.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Derives a schema from a given value.
+ *
+ * @param {any} data
+ * @returns {import('../types').DataSchema}
+ */
+export function deriveSchemaFromValue(data: any): import("../types").DataSchema;

package/dist/src/lib/validation.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Create validation messages for informational purposes
+ * @param {string} fieldPath - Field path
+ * @param {string} state - Message state ('info', 'warning', 'success')
+ * @param {string} text - Message text
+ * @returns {Object} Field path to message mapping
+ */
+export function createMessage(fieldPath: string, state: string, text: string): Object;
+/**
+ * Validate a single field value against its schema
+ * @param {any} value - Field value to validate
+ * @param {Object} fieldSchema - Field schema definition
+ * @param {string} [fieldLabel] - Field label for error messages
+ * @returns {ValidationMessage|null} Validation message or null if valid
+ */
+export function validateField(value: any, fieldSchema: Object, fieldLabel?: string): ValidationMessage | null;
+/**
+ * Validate all fields in a data object
+ * @param {Object} data - Data object to validate
+ * @param {Object} schema - Schema object with properties
+ * @param {Object} layout - Layout object with element definitions
+ * @returns {Object} Validation results keyed by field path
+ */
+export function validateAll(data: Object, schema: Object, layout: Object): Object;
+export namespace patterns {
+    let email: RegExp;
+    let phone: RegExp;
+    let url: RegExp;
+    let zipCode: RegExp;
+    let creditCard: RegExp;
+}
+export type ValidationMessage = {
+    /**
+     * - Message state: 'error', 'warning', 'info', 'success'
+     */
+    state: string;
+    /**
+     * - Message text content
+     */
+    text: string;
+};

package/dist/src/types.d.ts

@@ -0,0 +1,5 @@
+export namespace types {
+    let string: import("svelte/legacy").LegacyComponentType;
+    let integer: import("svelte/legacy").LegacyComponentType;
+    let phone: import("svelte/legacy").LegacyComponentType;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/forms",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Form building components for Rokkit applications",
   "repository": {
     "type": "git",