@rilaykit/core 0.1.1-alpha.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,158 +1,536 @@
1
- import React from 'react';
2
- import { z } from 'zod';
1
+ import { StandardSchemaV1 } from '@standard-schema/spec';
2
+ import * as React$1 from 'react';
3
+ import React__default from 'react';
3
4
 
4
5
  /**
5
- * Main configuration class for Rilay form components and workflows
6
- * Manages component registration, retrieval, and configuration
6
+ * A graph that tracks which fields depend on which other fields for condition evaluation.
7
+ *
8
+ * This enables efficient re-evaluation of conditions when values change:
9
+ * instead of re-evaluating ALL conditions when ANY value changes,
10
+ * we only re-evaluate conditions that depend on the changed value.
11
+ *
12
+ * @example
13
+ * ```ts
14
+ * const graph = new ConditionDependencyGraph();
15
+ *
16
+ * // Add field with its conditions
17
+ * graph.addField('dependentField', {
18
+ * visible: when('triggerField').equals('show')
19
+ * });
20
+ *
21
+ * // When 'triggerField' changes, get affected fields
22
+ * const affected = graph.getAffectedFields('triggerField');
23
+ * // affected = ['dependentField']
24
+ * ```
7
25
  */
8
- declare class ril {
9
- private components;
10
- private formRenderConfig;
11
- private workflowRenderConfig;
12
- static create(): ril;
26
+ declare class ConditionDependencyGraph {
13
27
  /**
14
- * Add a component to the configuration
15
- * @param subType - The component subtype (e.g., 'text', 'email', 'heading')
16
- * @param config - Component configuration without id and subType
17
- * @returns The ril instance for chaining
28
+ * Maps field IDs to their dependencies (fields they depend on)
29
+ * fieldId -> Set of field paths it depends on
18
30
  */
19
- addComponent<TProps = any>(subType: InputType | LayoutType, config: Omit<ComponentConfig<TProps>, 'id' | 'subType'> & {
20
- id?: string;
21
- }): this;
31
+ private readonly fieldDependencies;
22
32
  /**
23
- * Set custom row renderer
24
- * @param renderer - Custom row renderer function
25
- * @returns The ril instance for chaining
33
+ * Reverse index: maps a field path to all fields that depend on it
34
+ * fieldPath -> Set of field IDs that have conditions depending on this path
26
35
  */
27
- setRowRenderer(renderer: FormRowRenderer): this;
36
+ private readonly reverseDependencies;
28
37
  /**
29
- * Set custom body renderer
30
- * @param renderer - Custom body renderer function
31
- * @returns The ril instance for chaining
38
+ * Adds a field with its conditional behavior to the graph.
39
+ *
40
+ * @param fieldId - The ID of the field
41
+ * @param conditions - The field's conditional behavior (visible, disabled, required, readonly)
32
42
  */
33
- setBodyRenderer(renderer: FormBodyRenderer): this;
43
+ addField(fieldId: string, conditions?: ConditionalBehavior): void;
34
44
  /**
35
- * Set custom submit button renderer
36
- * @param renderer - Custom submit button renderer function
37
- * @returns The ril instance for chaining
45
+ * Removes a field from the graph.
46
+ *
47
+ * @param fieldId - The ID of the field to remove
38
48
  */
39
- setSubmitButtonRenderer(renderer: FormSubmitButtonRenderer): this;
49
+ removeField(fieldId: string): void;
40
50
  /**
41
- * Set complete form render configuration
42
- * @param config - Form render configuration
43
- * @returns The ril instance for chaining
51
+ * Gets all field IDs that have conditions depending on a specific field path.
52
+ *
53
+ * When a value at `changedPath` changes, these are the fields whose
54
+ * conditions need to be re-evaluated.
55
+ *
56
+ * @param changedPath - The field path that changed
57
+ * @returns Array of field IDs that depend on this path
44
58
  */
45
- setFormRenderConfig(config: FormRenderConfig): this;
59
+ getAffectedFields(changedPath: string): string[];
46
60
  /**
47
- * Get current form render configuration
48
- * @returns Current form render configuration
61
+ * Gets all field IDs affected by changes to multiple paths.
62
+ *
63
+ * @param changedPaths - Array of field paths that changed
64
+ * @returns Array of unique field IDs that depend on any of these paths
49
65
  */
50
- getFormRenderConfig(): FormRenderConfig;
66
+ getAffectedFieldsMultiple(changedPaths: string[]): string[];
51
67
  /**
52
- * Set custom stepper renderer for workflows
53
- * @param renderer - Custom stepper renderer function
54
- * @returns The ril instance for chaining
68
+ * Gets the dependencies for a specific field.
69
+ *
70
+ * @param fieldId - The ID of the field
71
+ * @returns Array of field paths this field depends on
55
72
  */
56
- setStepperRenderer(renderer: WorkflowStepperRenderer): this;
73
+ getDependencies(fieldId: string): string[];
57
74
  /**
58
- * Set custom workflow navigation renderer
59
- * @param renderer - Custom workflow navigation renderer function
60
- * @returns The ril instance for chaining
75
+ * Checks if a field has any dependencies.
76
+ *
77
+ * @param fieldId - The ID of the field
78
+ * @returns True if the field has conditional dependencies
61
79
  */
62
- setWorkflowNavigationRenderer(renderer: WorkflowNavigationRenderer): this;
80
+ hasDependencies(fieldId: string): boolean;
63
81
  /**
64
- * Set complete workflow render configuration
65
- * @param config - Workflow render configuration
66
- * @returns The ril instance for chaining
82
+ * Gets all fields in the graph.
83
+ *
84
+ * @returns Array of all field IDs
67
85
  */
68
- setWorkflowRenderConfig(config: WorkflowRenderConfig): this;
86
+ getAllFields(): string[];
69
87
  /**
70
- * Get current workflow render configuration
71
- * @returns Current workflow render configuration
88
+ * Gets all unique dependency paths in the graph.
89
+ *
90
+ * @returns Array of all field paths that are dependencies
72
91
  */
73
- getWorkflowRenderConfig(): WorkflowRenderConfig;
92
+ getAllDependencyPaths(): string[];
74
93
  /**
75
- * @deprecated Use setFormRenderConfig() instead
94
+ * Clears the entire graph.
76
95
  */
77
- setRenderConfig(config: FormRenderConfig): this;
96
+ clear(): void;
78
97
  /**
79
- * Get a component by its ID
80
- * @param id - Component ID
81
- * @returns Component configuration or undefined
98
+ * Gets the size of the graph (number of fields).
82
99
  */
83
- getComponent(id: string): ComponentConfig | undefined;
100
+ get size(): number;
84
101
  /**
85
- * List components by type (input or layout)
86
- * @param type - Component type
87
- * @returns Array of matching components
102
+ * Creates a debug representation of the graph.
103
+ * Useful for development and testing.
88
104
  */
89
- getComponentsByType(type: ComponentType): ComponentConfig[];
105
+ toDebugObject(): {
106
+ fields: Record<string, string[]>;
107
+ reverseDeps: Record<string, string[]>;
108
+ };
109
+ }
110
+
111
+ type ConditionOperator = 'equals' | 'notEquals' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual' | 'contains' | 'notContains' | 'in' | 'notIn' | 'matches' | 'exists' | 'notExists';
112
+ type LogicalOperator = 'and' | 'or';
113
+ type ConditionValue = string | number | boolean | null | undefined | Array<string | number | boolean>;
114
+ interface ConditionConfig {
115
+ field: string;
116
+ operator: ConditionOperator;
117
+ value?: ConditionValue;
118
+ conditions?: ConditionConfig[];
119
+ logicalOperator?: LogicalOperator;
120
+ }
121
+ type ConditionEvaluator = (data: Record<string, any>) => boolean;
122
+ interface ConditionBuilder extends ConditionConfig {
123
+ equals(value: ConditionValue): ConditionBuilder;
124
+ notEquals(value: ConditionValue): ConditionBuilder;
125
+ greaterThan(value: number): ConditionBuilder;
126
+ lessThan(value: number): ConditionBuilder;
127
+ greaterThanOrEqual(value: number): ConditionBuilder;
128
+ lessThanOrEqual(value: number): ConditionBuilder;
129
+ contains(value: string): ConditionBuilder;
130
+ notContains(value: string): ConditionBuilder;
131
+ in(values: Array<string | number | boolean>): ConditionBuilder;
132
+ notIn(values: Array<string | number | boolean>): ConditionBuilder;
133
+ matches(pattern: string | RegExp): ConditionBuilder;
134
+ exists(): ConditionBuilder;
135
+ notExists(): ConditionBuilder;
136
+ and(condition: ConditionBuilder | ConditionConfig): ConditionBuilder;
137
+ or(condition: ConditionBuilder | ConditionConfig): ConditionBuilder;
138
+ build(): ConditionConfig;
139
+ evaluate(data: Record<string, any>): boolean;
140
+ }
141
+ declare function when(field: string): ConditionBuilder;
142
+ declare function evaluateCondition(condition: ConditionConfig, data: Record<string, any>): boolean;
143
+
144
+ /**
145
+ * Extracts all field paths that a condition depends on.
146
+ *
147
+ * This is useful for building a dependency graph that knows which
148
+ * conditions need to be re-evaluated when a specific field changes.
149
+ *
150
+ * @param condition - The condition to extract dependencies from
151
+ * @returns An array of unique field paths
152
+ *
153
+ * @example
154
+ * ```ts
155
+ * const condition = when('field1').equals('value').and(when('field2').exists());
156
+ * const deps = extractConditionDependencies(condition.build());
157
+ * // deps = ['field1', 'field2']
158
+ *
159
+ * const nestedCondition = when('step1.field1').equals('value');
160
+ * const nestedDeps = extractConditionDependencies(nestedCondition.build());
161
+ * // nestedDeps = ['step1.field1']
162
+ * ```
163
+ */
164
+ declare function extractConditionDependencies(condition: ConditionConfig | ConditionBuilder | undefined | null): string[];
165
+ /**
166
+ * Extracts dependencies from multiple conditions (e.g., visible, disabled, required).
167
+ *
168
+ * @param behaviors - Object containing condition configurations
169
+ * @returns An array of unique field paths from all conditions
170
+ */
171
+ declare function extractAllDependencies(behaviors: Record<string, ConditionConfig | ConditionBuilder | undefined | null>): string[];
172
+
173
+ /**
174
+ * Validation result for async operations
175
+ */
176
+ interface AsyncValidationResult {
177
+ isValid: boolean;
178
+ errors: string[];
179
+ warnings?: string[];
180
+ }
181
+ /**
182
+ * Public interface for Rilay instances
183
+ * Exposes only the methods necessary for the public API
184
+ */
185
+ interface RilayInstance<C> {
186
+ addComponent<NewType extends string, TProps = any>(type: NewType, config: Omit<ComponentConfig<TProps>, 'id' | 'type'>): RilayInstance<C & {
187
+ [K in NewType]: TProps;
188
+ }>;
189
+ configure(config: Partial<FormRenderConfig & WorkflowRenderConfig>): RilayInstance<C>;
190
+ getComponent<T extends keyof C & string>(id: T): ComponentConfig<C[T]> | undefined;
191
+ getComponent(id: string): ComponentConfig | undefined;
192
+ getAllComponents(): ComponentConfig[];
193
+ hasComponent(id: string): boolean;
194
+ getFormRenderConfig(): FormRenderConfig;
195
+ getWorkflowRenderConfig(): WorkflowRenderConfig;
196
+ getStats(): {
197
+ total: number;
198
+ byType: Record<string, number>;
199
+ hasCustomRenderers: {
200
+ row: boolean;
201
+ body: boolean;
202
+ submitButton: boolean;
203
+ field: boolean;
204
+ repeatable: boolean;
205
+ repeatableItem: boolean;
206
+ stepper: boolean;
207
+ workflowNextButton: boolean;
208
+ workflowPreviousButton: boolean;
209
+ workflowSkipButton: boolean;
210
+ };
211
+ };
212
+ validate(): string[];
213
+ validateAsync(): Promise<AsyncValidationResult>;
214
+ clone(): RilayInstance<C>;
215
+ removeComponent(id: string): RilayInstance<C>;
216
+ clear(): RilayInstance<C>;
217
+ }
218
+ /**
219
+ * Main configuration class for Rilay form components and workflows
220
+ * Manages component registration, retrieval, and configuration with immutable API
221
+ */
222
+ declare class ril<C> implements RilayInstance<C> {
223
+ private components;
224
+ private formRenderConfig;
225
+ private workflowRenderConfig;
90
226
  /**
91
- * List components by sub-type
92
- * @param subType - Component sub-type
93
- * @returns Array of matching components
227
+ * Static factory method to create a new ril instance
94
228
  */
95
- getComponentsBySubType(subType: InputType | LayoutType): ComponentConfig[];
229
+ static create<CT>(): ril<CT>;
96
230
  /**
97
- * Get components by category
98
- * @param category - Component category
99
- * @returns Array of matching components
231
+ * Add a component to the configuration (immutable)
232
+ * Returns a new instance with the added component
233
+ *
234
+ * @param type - The component type (e.g., 'text', 'email', 'heading'), used as a unique identifier.
235
+ * @param config - Component configuration without id and type
236
+ * @returns A new ril instance with the added component
237
+ *
238
+ * @example
239
+ * ```typescript
240
+ * // Component with default validation
241
+ * const factory = ril.create()
242
+ * .addComponent('email', {
243
+ * name: 'Email Input',
244
+ * renderer: EmailInput,
245
+ * validation: {
246
+ * validators: [email('Format email invalide')],
247
+ * validateOnBlur: true,
248
+ * }
249
+ * });
250
+ * ```
100
251
  */
101
- getComponentsByCategory(category: string): ComponentConfig[];
252
+ addComponent<NewType extends string, TProps = any>(type: NewType, config: Omit<ComponentConfig<TProps>, 'id' | 'type'>): ril<C & {
253
+ [K in NewType]: TProps;
254
+ }>;
102
255
  /**
103
- * List all registered components
104
- * @returns Array of all components
256
+ * Universal configuration method with deep merge support (immutable)
257
+ *
258
+ * This method provides a unified API to configure both form and workflow renderers
259
+ * in a single call, automatically categorizing and applying the appropriate configurations
260
+ * using recursive deep merge.
261
+ *
262
+ * @param config - Configuration object containing renderer settings
263
+ * @returns A new ril instance with the updated configuration
264
+ *
265
+ * @example
266
+ * ```typescript
267
+ * // Configure with nested settings
268
+ * const config = ril.create()
269
+ * .configure({
270
+ * rowRenderer: CustomRowRenderer,
271
+ * submitButtonRenderer: CustomSubmitButton,
272
+ * // Deep nested configuration example
273
+ * formStyles: {
274
+ * layout: {
275
+ * spacing: 'large',
276
+ * alignment: 'center'
277
+ * }
278
+ * }
279
+ * });
280
+ * ```
105
281
  */
106
- getAllComponents(): ComponentConfig[];
282
+ configure(config: Partial<FormRenderConfig & WorkflowRenderConfig>): ril<C>;
107
283
  /**
108
- * Check if a component exists
109
- * @param id - Component ID
110
- * @returns True if component exists
284
+ * Configuration getters
111
285
  */
112
- hasComponent(id: string): boolean;
286
+ getFormRenderConfig(): FormRenderConfig;
287
+ getWorkflowRenderConfig(): WorkflowRenderConfig;
113
288
  /**
114
- * Remove a component from the configuration
115
- * @param id - Component ID
116
- * @returns True if component was removed
289
+ * Component management methods
117
290
  */
118
- removeComponent(id: string): boolean;
291
+ getComponent<T extends keyof C & string>(id: T): ComponentConfig<C[T]> | undefined;
292
+ getAllComponents(): ComponentConfig[];
293
+ hasComponent(id: string): boolean;
119
294
  /**
120
- * Clear all components
295
+ * Remove a component from the configuration (immutable)
296
+ * Returns a new instance without the specified component
297
+ *
298
+ * @param id - The component ID to remove
299
+ * @returns A new ril instance without the component
121
300
  */
122
- clear(): void;
301
+ removeComponent(id: string): ril<C>;
123
302
  /**
124
- * Export configuration as a plain object
125
- * @returns Object with component configurations
303
+ * Clear all components from the configuration (immutable)
304
+ * Returns a new instance with no components
305
+ *
306
+ * @returns A new empty ril instance
126
307
  */
127
- export(): Record<string, ComponentConfig>;
308
+ clear(): ril<C>;
128
309
  /**
129
- * Import configuration from a plain object
130
- * @param config - Object with component configurations
131
- * @returns The ril instance for chaining
310
+ * Create a deep copy of the current ril instance
132
311
  */
133
- import(config: Record<string, ComponentConfig>): this;
312
+ clone(): ril<C>;
134
313
  /**
135
- * Get statistics about registered components and renderers
136
- * @returns Object with comprehensive statistics
314
+ * Enhanced statistics with more detailed information
137
315
  */
138
316
  getStats(): {
139
317
  total: number;
140
- byType: Record<ComponentType, number>;
141
- bySubType: Record<string, number>;
142
- byCategory: Record<string, number>;
318
+ byType: Record<string, number>;
143
319
  hasCustomRenderers: {
144
320
  row: boolean;
145
321
  body: boolean;
146
322
  submitButton: boolean;
323
+ field: boolean;
324
+ repeatable: boolean;
325
+ repeatableItem: boolean;
147
326
  stepper: boolean;
148
- workflowNavigation: boolean;
327
+ workflowNextButton: boolean;
328
+ workflowPreviousButton: boolean;
329
+ workflowSkipButton: boolean;
149
330
  };
150
331
  };
151
332
  /**
152
- * Validate the configuration
153
- * @returns Array of validation errors
333
+ * Synchronous validation using shared utilities
154
334
  */
155
335
  validate(): string[];
336
+ /**
337
+ * Asynchronous validation with structured error handling
338
+ * Ideal for CI/CD pipelines and advanced validation scenarios
339
+ */
340
+ validateAsync(): Promise<AsyncValidationResult>;
341
+ }
342
+
343
+ type ValidationState = 'idle' | 'validating' | 'valid' | 'invalid';
344
+ /**
345
+ * Field state without actions - used for selectors
346
+ */
347
+ interface FieldState {
348
+ readonly value: unknown;
349
+ readonly errors: ValidationError[];
350
+ readonly validationState: ValidationState;
351
+ readonly touched: boolean;
352
+ readonly dirty: boolean;
353
+ }
354
+ /**
355
+ * Field conditions - visibility, disabled, required, readonly
356
+ */
357
+ interface FieldConditions {
358
+ readonly visible: boolean;
359
+ readonly disabled: boolean;
360
+ readonly required: boolean;
361
+ readonly readonly: boolean;
362
+ }
363
+ /**
364
+ * Field actions - stable references for setValue, validate, etc.
365
+ */
366
+ interface FieldActions {
367
+ readonly setValue: (value: unknown) => void;
368
+ readonly setTouched: () => void;
369
+ readonly validate: () => Promise<ValidationResult>;
370
+ readonly clearErrors: () => void;
371
+ }
372
+ /**
373
+ * Complete field context - combines state, conditions and actions
374
+ * Used by component renderers for full field access
375
+ */
376
+ interface FieldContext extends FieldState, FieldConditions {
377
+ readonly id: string;
378
+ readonly componentId: string;
379
+ readonly defaultValue?: unknown;
380
+ readonly actions: FieldActions;
381
+ }
382
+ /**
383
+ * Form state without actions - used for selectors
384
+ */
385
+ interface FormState {
386
+ readonly values: Record<string, unknown>;
387
+ readonly errors: Record<string, ValidationError[]>;
388
+ readonly validationStates: Record<string, ValidationState>;
389
+ readonly touched: Record<string, boolean>;
390
+ readonly isDirty: boolean;
391
+ readonly isSubmitting: boolean;
392
+ readonly isValid: boolean;
393
+ }
394
+ /**
395
+ * Form actions - stable references
396
+ */
397
+ interface FormActions {
398
+ readonly setValue: (fieldId: string, value: unknown) => void;
399
+ readonly setTouched: (fieldId: string) => void;
400
+ readonly setErrors: (fieldId: string, errors: ValidationError[]) => void;
401
+ readonly setValidationState: (fieldId: string, state: ValidationState) => void;
402
+ readonly setSubmitting: (isSubmitting: boolean) => void;
403
+ readonly submit: () => Promise<boolean>;
404
+ readonly reset: (values?: Record<string, unknown>) => void;
405
+ readonly validate: () => Promise<ValidationResult>;
406
+ readonly validateField: (fieldId: string, value?: unknown) => Promise<ValidationResult>;
407
+ }
408
+ /**
409
+ * Complete form context - combines state and actions
410
+ */
411
+ interface FormContextValue extends FormState {
412
+ readonly formId: string;
413
+ readonly actions: FormActions;
414
+ readonly getFieldState: (fieldId: string) => FieldState;
415
+ readonly getFieldConditions: (fieldId: string) => FieldConditions;
416
+ }
417
+ /**
418
+ * Props passed to component renderers (v2)
419
+ * Replaces the old ComponentRenderProps with spread [key: string]: any
420
+ */
421
+ interface ComponentRenderPropsV2<TProps = unknown> {
422
+ /** Field identifier */
423
+ readonly id: string;
424
+ /** Component-specific props (label, placeholder, options, etc.) */
425
+ readonly props: TProps;
426
+ /** Field state (value, errors, touched, etc.) */
427
+ readonly field: FieldState;
428
+ /** Field conditions (visible, disabled, required, readonly) */
429
+ readonly conditions: FieldConditions;
430
+ /** Stable action references */
431
+ readonly actions: FieldActions;
432
+ }
433
+ /**
434
+ * Props passed to field wrapper renderers (v2)
435
+ */
436
+ interface FieldRendererPropsV2 {
437
+ /** Rendered component content */
438
+ readonly children: React.ReactNode;
439
+ /** Field identifier */
440
+ readonly id: string;
441
+ /** Field state */
442
+ readonly field: FieldState;
443
+ /** Field conditions */
444
+ readonly conditions: FieldConditions;
445
+ /** Component props (for label, placeholder, helpText, etc.) */
446
+ readonly componentProps: Record<string, unknown>;
447
+ }
448
+ /**
449
+ * Props passed to form submit button renderer (v2)
450
+ */
451
+ interface FormSubmitButtonRendererPropsV2 {
452
+ /** Whether form is currently submitting */
453
+ readonly isSubmitting: boolean;
454
+ /** Whether form is valid (no errors) */
455
+ readonly isValid: boolean;
456
+ /** Whether form has been modified */
457
+ readonly isDirty: boolean;
458
+ /** Submit handler */
459
+ readonly onSubmit: () => void;
460
+ /** Reset handler */
461
+ readonly onReset: () => void;
462
+ /** Form data access (for advanced use cases) */
463
+ readonly form: {
464
+ readonly values: Record<string, unknown>;
465
+ readonly errors: Record<string, ValidationError[]>;
466
+ };
467
+ /** Optional className */
468
+ readonly className?: string;
469
+ /** Optional children */
470
+ readonly children?: React.ReactNode;
471
+ }
472
+ /**
473
+ * Step state for workflow
474
+ */
475
+ interface WorkflowStepState {
476
+ readonly stepIndex: number;
477
+ readonly stepId: string;
478
+ readonly isFirst: boolean;
479
+ readonly isLast: boolean;
480
+ readonly isVisible: boolean;
481
+ readonly isSkippable: boolean;
482
+ }
483
+ /**
484
+ * Navigation state for workflow
485
+ */
486
+ interface WorkflowNavigationState {
487
+ readonly canGoNext: boolean;
488
+ readonly canGoPrevious: boolean;
489
+ readonly canSkip: boolean;
490
+ readonly isTransitioning: boolean;
491
+ }
492
+ /**
493
+ * Progress state for workflow
494
+ */
495
+ interface WorkflowProgressState {
496
+ readonly totalSteps: number;
497
+ readonly visibleSteps: number;
498
+ readonly currentStepIndex: number;
499
+ readonly visitedSteps: ReadonlySet<string>;
500
+ readonly passedSteps: ReadonlySet<string>;
501
+ }
502
+ /**
503
+ * Complete workflow step context
504
+ */
505
+ interface WorkflowStepContext {
506
+ readonly step: WorkflowStepState;
507
+ readonly navigation: WorkflowNavigationState;
508
+ readonly progress: WorkflowProgressState;
509
+ readonly stepData: Record<string, unknown>;
510
+ readonly allData: Record<string, unknown>;
511
+ }
512
+ /**
513
+ * Props passed to workflow button renderers (v2)
514
+ */
515
+ interface WorkflowButtonRendererPropsV2 {
516
+ /** Navigation state */
517
+ readonly navigation: WorkflowNavigationState;
518
+ /** Progress state */
519
+ readonly progress: WorkflowProgressState;
520
+ /** Current step state */
521
+ readonly step: WorkflowStepState;
522
+ /** Whether workflow is submitting */
523
+ readonly isSubmitting: boolean;
524
+ /** Step data */
525
+ readonly stepData: Record<string, unknown>;
526
+ /** All workflow data */
527
+ readonly allData: Record<string, unknown>;
528
+ /** Action handler (next/previous/skip/submit) */
529
+ readonly onAction: () => void;
530
+ /** Optional className */
531
+ readonly className?: string;
532
+ /** Optional children */
533
+ readonly children?: React.ReactNode;
156
534
  }
157
535
 
158
536
  interface RilayLicenseConfig {
@@ -160,103 +538,330 @@ interface RilayLicenseConfig {
160
538
  readonly environment?: 'development' | 'production';
161
539
  readonly allowTrial?: boolean;
162
540
  }
163
- type ComponentType = 'input' | 'layout';
164
- type InputType = 'text' | 'email' | 'password' | 'number' | 'select' | 'checkbox' | 'textarea' | 'file' | 'date';
165
- type LayoutType = 'heading' | 'paragraph' | 'container' | 'divider' | 'spacer' | 'alert';
166
- interface ValidationResult {
167
- readonly isValid: boolean;
168
- readonly errors: ValidationError[];
169
- readonly warnings?: ValidationWarning[];
170
- }
171
541
  interface ValidationError {
172
- readonly code: string;
173
542
  readonly message: string;
174
- readonly path?: string[];
543
+ readonly code?: string;
544
+ readonly path?: string;
175
545
  }
176
- interface ValidationWarning {
177
- readonly code: string;
178
- readonly message: string;
179
- readonly path?: string[];
546
+ interface ValidationResult {
547
+ readonly isValid: boolean;
548
+ readonly errors: ValidationError[];
549
+ readonly value?: any;
180
550
  }
181
551
  interface ValidationContext {
182
- readonly fieldId: string;
183
- readonly formData: Record<string, any>;
184
- readonly fieldProps: Record<string, any>;
185
- readonly touched: boolean;
186
- readonly dirty: boolean;
552
+ readonly fieldId?: string;
553
+ readonly formId?: string;
554
+ readonly stepId?: string;
555
+ readonly workflowId?: string;
556
+ readonly allFormData?: Record<string, any>;
557
+ readonly stepData?: Record<string, any>;
558
+ readonly workflowData?: Record<string, any>;
187
559
  }
188
- type ValidatorFunction<TProps = any> = (value: any, context: ValidationContext, props: TProps) => ValidationResult | Promise<ValidationResult>;
189
- interface ValidationConfig<TProps = any> {
190
- readonly validator?: ValidatorFunction<TProps>;
191
- readonly debounceMs?: number;
560
+ /** @internal - Use Standard Schema instead */
561
+ type FieldValidator<T = any> = (value: T, context: ValidationContext) => ValidationResult | Promise<ValidationResult>;
562
+ /** @internal - Use Standard Schema instead */
563
+ type FormValidator<T = Record<string, any>> = (formData: T, context: ValidationContext) => ValidationResult | Promise<ValidationResult>;
564
+ type StandardSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output>;
565
+ type InferInput<T> = T extends StandardSchema<infer I, any> ? I : unknown;
566
+ type InferOutput<T> = T extends StandardSchema<any, infer O> ? O : unknown;
567
+ interface FieldValidationConfig<T = any> {
568
+ /**
569
+ * Validation rules using Standard Schema interface
570
+ * Accepts: single schema, array of schemas, or any Standard Schema compatible validation
571
+ *
572
+ * @example Single schema
573
+ * validate: z.string().email()
574
+ *
575
+ * @example Built-in validators
576
+ * validate: required()
577
+ *
578
+ * @example Multiple validations
579
+ * validate: [required(), email()]
580
+ *
581
+ * @example Mixed schemas + validators
582
+ * validate: [z.string(), required(), customValidator()]
583
+ */
584
+ readonly validate?: StandardSchema<T> | StandardSchema<T>[];
192
585
  readonly validateOnChange?: boolean;
193
586
  readonly validateOnBlur?: boolean;
587
+ readonly debounceMs?: number;
588
+ }
589
+ interface FormValidationConfig<T extends Record<string, any> = Record<string, any>> {
590
+ /**
591
+ * Form-level validation using Standard Schema interface
592
+ *
593
+ * @example Object schema
594
+ * validate: z.object({ email: z.string().email(), name: z.string() })
595
+ *
596
+ * @example Custom form validator
597
+ * validate: customFormValidator()
598
+ */
599
+ readonly validate?: StandardSchema<T> | StandardSchema<T>[];
194
600
  readonly validateOnSubmit?: boolean;
195
- readonly dependencies?: string[];
601
+ readonly validateOnStepChange?: boolean;
602
+ }
603
+ type ComponentRenderer<TProps = any> = (props: ComponentRenderProps<TProps>) => React__default.ReactElement;
604
+ type RendererChildrenFunction<TProps = any> = (props: TProps) => React__default.ReactNode;
605
+ interface ComponentRendererBaseProps<TProps = any> {
606
+ className?: string;
607
+ children?: React__default.ReactNode | RendererChildrenFunction<TProps>;
608
+ renderAs?: 'default' | 'children' | boolean;
609
+ }
610
+ interface ComponentRendererWrapperProps<TProps = any> extends Omit<ComponentRendererBaseProps<TProps>, 'className'> {
611
+ name: string;
612
+ props: TProps;
613
+ renderer?: RendererChildrenFunction<TProps>;
196
614
  }
197
- type ComponentRenderer<TProps = any> = (props: ComponentRenderProps<TProps>) => React.ReactElement;
198
615
  interface ComponentRenderProps<TProps = any> {
199
616
  id: string;
200
617
  props: TProps;
201
618
  value?: any;
202
619
  onChange?: (value: any) => void;
203
620
  onBlur?: () => void;
204
- error?: ValidationError[];
205
- warnings?: ValidationWarning[];
206
- touched?: boolean;
207
621
  disabled?: boolean;
622
+ error?: ValidationError[];
208
623
  isValidating?: boolean;
209
624
  [key: string]: any;
210
625
  }
211
- interface ComponentOptions<TProps = any> {
212
- readonly configurable?: Array<{
213
- key: keyof TProps;
214
- type: 'string' | 'number' | 'boolean' | 'select' | 'array';
626
+ /**
627
+ * Property editor definition for builder property panel
628
+ * Generic and extensible to support any custom editor type
629
+ */
630
+ interface PropertyEditorDefinition<TValue = any> {
631
+ /** Property key in component props */
632
+ readonly key: string;
633
+ /** Display label in property panel */
634
+ readonly label: string;
635
+ /**
636
+ * Editor type - can be any string to support custom editors
637
+ * Built-in types: 'text', 'number', 'boolean', 'select', 'multiselect', 'color', 'textarea', 'json'
638
+ * Custom types: 'phone', 'currency', 'location', 'rating', 'file-upload', etc.
639
+ */
640
+ readonly editorType: string;
641
+ /** Optional description/help text */
642
+ readonly helpText?: string;
643
+ /** Default value for this property */
644
+ readonly defaultValue?: TValue;
645
+ /** Options for select/multiselect editors */
646
+ readonly options?: Array<{
215
647
  label: string;
216
- options?: any[];
217
- default?: any;
648
+ value: any;
649
+ [key: string]: any;
218
650
  }>;
219
- readonly previewProps?: Partial<TProps>;
651
+ /** Validation function for the property value */
652
+ readonly validate?: (value: TValue) => boolean | string | Promise<boolean | string>;
653
+ /** Group/section for organizing properties */
654
+ readonly group?: string;
655
+ /** Whether this property is required */
656
+ readonly required?: boolean;
657
+ /** Placeholder text for input fields */
658
+ readonly placeholder?: string;
659
+ /** Custom editor component for advanced use cases */
660
+ readonly customEditor?: React__default.ComponentType<PropertyEditorProps<TValue>>;
661
+ /** Additional configuration specific to the editor type */
662
+ readonly editorConfig?: Record<string, any>;
663
+ /** Dependencies - other properties that affect this one */
664
+ readonly dependencies?: string[];
665
+ /** Conditional rendering based on other property values */
666
+ readonly visible?: (props: Record<string, any>) => boolean;
667
+ /** Transform value before saving */
668
+ readonly transform?: (value: TValue) => any;
669
+ /** Parse value when loading */
670
+ readonly parse?: (value: any) => TValue;
671
+ }
672
+ /**
673
+ * Props passed to custom property editors
674
+ */
675
+ interface PropertyEditorProps<TValue = any> {
676
+ /** Current property value */
677
+ readonly value: TValue;
678
+ /** Callback to update the value */
679
+ readonly onChange: (value: TValue) => void;
680
+ /** Property definition */
681
+ readonly definition: PropertyEditorDefinition<TValue>;
682
+ /** All current property values (for dependencies) */
683
+ readonly allValues: Record<string, any>;
684
+ /** Whether the field is disabled */
685
+ readonly disabled?: boolean;
686
+ /** Validation errors */
687
+ readonly errors?: string[];
688
+ }
689
+ /**
690
+ * Builder metadata for visual editing capabilities
691
+ * This is optional and only used by @rilaykit/builder
692
+ * Fully generic to support any component type and configuration
693
+ */
694
+ interface ComponentBuilderMetadata<TProps = any> {
695
+ /** Category for grouping in component palette (e.g., 'Input', 'Layout', 'Advanced') */
696
+ readonly category?: string;
697
+ /** Icon identifier (e.g., 'text', 'email', 'calendar') */
220
698
  readonly icon?: string;
699
+ /** Whether this component should be hidden from the builder palette */
700
+ readonly hidden?: boolean;
701
+ /** Preview component or description for the palette */
702
+ readonly preview?: React__default.ReactNode;
703
+ /** Editable properties configuration for property panel */
704
+ readonly editableProps?: PropertyEditorDefinition[];
705
+ /** Tags for search and filtering */
221
706
  readonly tags?: string[];
707
+ /**
708
+ * Custom field schema for advanced type systems
709
+ * Allows defining complex field types with their own validation and structure
710
+ */
711
+ readonly fieldSchema?: FieldSchemaDefinition<TProps>;
712
+ }
713
+ /**
714
+ * Field schema definition for complex field types
715
+ * Supports defining custom field types with validation, defaults, and metadata
716
+ */
717
+ interface FieldSchemaDefinition<TProps = any> {
718
+ /** Field type identifier (e.g., 'location', 'phone', 'currency') */
719
+ readonly type: string;
720
+ /** Schema validation (Zod, Yup, or any Standard Schema) */
721
+ readonly schema?: any;
722
+ /** Default configuration for this field type */
723
+ readonly defaultConfig?: Partial<TProps>;
724
+ /** Sub-fields for complex types (e.g., Location has address, city, country) */
725
+ readonly subFields?: Array<{
726
+ key: string;
727
+ label: string;
728
+ type: string;
729
+ required?: boolean;
730
+ }>;
731
+ /** Custom serialization for complex data structures */
732
+ readonly serialize?: (value: any) => any;
733
+ /** Custom deserialization for complex data structures */
734
+ readonly deserialize?: (value: any) => any;
222
735
  }
223
736
  interface ComponentConfig<TProps = any> {
224
737
  readonly id: string;
225
- readonly type: ComponentType;
226
- readonly subType: InputType | LayoutType;
738
+ readonly type: string;
227
739
  readonly name: string;
228
740
  readonly description?: string;
229
- readonly category?: string;
230
741
  readonly renderer: ComponentRenderer<TProps>;
231
- readonly options?: ComponentOptions<TProps>;
232
- readonly validation?: ValidationConfig<TProps>;
233
742
  readonly defaultProps?: Partial<TProps>;
743
+ readonly useFieldRenderer?: boolean;
744
+ readonly validation?: FieldValidationConfig;
745
+ /** Optional builder metadata for visual editing (only used by @rilaykit/builder) */
746
+ readonly builder?: ComponentBuilderMetadata;
747
+ }
748
+ interface ConditionalBehavior {
749
+ readonly visible?: ConditionConfig;
750
+ readonly disabled?: ConditionConfig;
751
+ readonly required?: ConditionConfig;
752
+ readonly readonly?: ConditionConfig;
753
+ }
754
+ interface StepConditionalBehavior {
755
+ readonly visible?: ConditionConfig;
756
+ readonly skippable?: ConditionConfig;
234
757
  }
235
758
  interface FormFieldConfig {
236
759
  readonly id: string;
237
760
  readonly componentId: string;
238
761
  readonly props: Record<string, any>;
239
- readonly validation?: ValidationConfig;
240
- readonly conditional?: ConditionalConfig;
762
+ readonly validation?: FieldValidationConfig;
763
+ readonly conditions?: ConditionalBehavior;
241
764
  }
242
765
  interface FormFieldRow {
766
+ readonly kind: 'fields';
243
767
  readonly id: string;
244
768
  readonly fields: FormFieldConfig[];
245
769
  readonly maxColumns?: number;
246
- readonly spacing?: 'tight' | 'normal' | 'loose';
247
- readonly alignment?: 'start' | 'center' | 'end' | 'stretch';
248
770
  }
249
- interface ConditionalConfig {
250
- readonly condition: (formData: Record<string, any>) => boolean;
251
- readonly action: 'show' | 'hide' | 'disable' | 'require';
771
+ interface RepeatableFieldConfig {
772
+ readonly id: string;
773
+ readonly rows: FormFieldRow[];
774
+ readonly allFields: FormFieldConfig[];
775
+ readonly min?: number;
776
+ readonly max?: number;
777
+ readonly defaultValue?: Record<string, unknown>;
778
+ readonly validation?: FieldValidationConfig;
779
+ }
780
+ interface RepeatableFieldItem {
781
+ readonly key: string;
782
+ readonly index: number;
783
+ readonly rows: FormFieldRow[];
784
+ readonly allFields: FormFieldConfig[];
785
+ }
786
+ interface FormRepeatableRow {
787
+ readonly kind: 'repeatable';
788
+ readonly id: string;
789
+ readonly repeatable: RepeatableFieldConfig;
790
+ }
791
+ type FormRowEntry = FormFieldRow | FormRepeatableRow;
792
+ interface RepeatableFieldRendererProps {
793
+ readonly repeatableId: string;
794
+ readonly items: RepeatableFieldItem[];
795
+ readonly canAdd: boolean;
796
+ readonly canRemove: boolean;
797
+ readonly onAdd: () => void;
798
+ readonly min?: number;
799
+ readonly max?: number;
800
+ readonly children: React__default.ReactNode;
252
801
  }
253
- interface StepLifecycleHooks {
254
- readonly onBeforeEnter?: (stepData: any, allData: any, context: WorkflowContext) => Promise<void>;
255
- readonly onAfterLeave?: (stepData: any, allData: any, context: WorkflowContext) => Promise<boolean>;
256
- readonly onValidate?: (stepData: any, context: WorkflowContext) => Promise<ValidationResult>;
257
- readonly onTransform?: (stepData: any, context: WorkflowContext) => Promise<any>;
258
- readonly onError?: (error: Error, context: WorkflowContext) => Promise<void>;
802
+ interface RepeatableItemRendererProps {
803
+ readonly item: RepeatableFieldItem;
804
+ readonly index: number;
805
+ readonly total: number;
806
+ readonly canRemove: boolean;
807
+ readonly canMoveUp: boolean;
808
+ readonly canMoveDown: boolean;
809
+ readonly onRemove: () => void;
810
+ readonly onMoveUp: () => void;
811
+ readonly onMoveDown: () => void;
812
+ readonly children: React__default.ReactNode;
259
813
  }
814
+ type RepeatableFieldRenderer = RendererChildrenFunction<RepeatableFieldRendererProps>;
815
+ type RepeatableItemRenderer = RendererChildrenFunction<RepeatableItemRendererProps>;
816
+ interface FormConfiguration<C extends Record<string, any> = Record<string, never>> {
817
+ readonly id: string;
818
+ readonly config: ril<C>;
819
+ readonly rows: FormRowEntry[];
820
+ readonly allFields: FormFieldConfig[];
821
+ readonly repeatableFields?: Record<string, RepeatableFieldConfig>;
822
+ readonly renderConfig?: FormRenderConfig;
823
+ readonly validation?: FormValidationConfig;
824
+ }
825
+ interface FormRenderConfig {
826
+ readonly rowRenderer?: FormRowRenderer;
827
+ readonly bodyRenderer?: FormBodyRenderer;
828
+ readonly submitButtonRenderer?: FormSubmitButtonRenderer;
829
+ readonly fieldRenderer?: FieldRenderer;
830
+ readonly repeatableRenderer?: RepeatableFieldRenderer;
831
+ readonly repeatableItemRenderer?: RepeatableItemRenderer;
832
+ }
833
+ interface FormComponentRendererProps {
834
+ children: React__default.ReactNode;
835
+ }
836
+ interface FormRowRendererProps {
837
+ row: FormFieldRow;
838
+ children: React__default.ReactNode;
839
+ className?: string;
840
+ }
841
+ interface FormBodyRendererProps {
842
+ formConfig: FormConfiguration;
843
+ children: React__default.ReactNode;
844
+ className?: string;
845
+ }
846
+ interface FormSubmitButtonRendererProps {
847
+ isSubmitting: boolean;
848
+ onSubmit: () => void;
849
+ className?: string;
850
+ children?: React__default.ReactNode;
851
+ }
852
+ interface FieldRendererProps {
853
+ children: React__default.ReactNode;
854
+ id: string;
855
+ disabled?: boolean;
856
+ error?: ValidationError[];
857
+ isValidating?: boolean;
858
+ touched?: boolean;
859
+ [key: string]: any;
860
+ }
861
+ type FormRowRenderer = RendererChildrenFunction<FormRowRendererProps>;
862
+ type FormBodyRenderer = RendererChildrenFunction<FormBodyRendererProps>;
863
+ type FormSubmitButtonRenderer = RendererChildrenFunction<FormSubmitButtonRendererProps>;
864
+ type FieldRenderer = RendererChildrenFunction<FieldRendererProps>;
260
865
  interface WorkflowContext {
261
866
  readonly workflowId: string;
262
867
  readonly currentStepIndex: number;
@@ -266,85 +871,70 @@ interface WorkflowContext {
266
871
  readonly isFirstStep: boolean;
267
872
  readonly isLastStep: boolean;
268
873
  readonly visitedSteps: Set<string>;
269
- readonly user?: any;
270
- }
271
- interface StepPermissions {
272
- readonly requiredRoles?: string[];
273
- readonly requiredPermissions?: string[];
274
- readonly customGuard?: (user: any, context: WorkflowContext) => boolean | Promise<boolean>;
275
- }
276
- interface DynamicStepConfig {
277
- readonly resolver: (previousData: any, context: WorkflowContext) => Promise<StepConfig[]>;
278
- readonly cacheKey?: string;
279
- readonly retryPolicy?: RetryPolicy;
874
+ readonly visibleVisitedSteps: Set<string>;
875
+ readonly passedSteps: Set<string>;
280
876
  }
281
- interface RetryPolicy {
282
- readonly maxRetries: number;
283
- readonly delayMs: number;
284
- readonly backoffMultiplier?: number;
285
- }
286
- interface ConditionalBranch {
287
- readonly condition: (data: any, context: WorkflowContext) => boolean | Promise<boolean>;
288
- readonly steps: StepConfig[];
289
- readonly fallback?: StepConfig[];
877
+ interface StepDataHelper {
878
+ /**
879
+ * Set data for a specific step by step ID
880
+ */
881
+ setStepData: (stepId: string, data: Record<string, any>) => void;
882
+ /**
883
+ * Set specific field values for a step
884
+ */
885
+ setStepFields: (stepId: string, fields: Record<string, any>) => void;
886
+ /**
887
+ * Get current data for a specific step
888
+ */
889
+ getStepData: (stepId: string) => Record<string, any>;
890
+ /**
891
+ * Set field value for the next step
892
+ */
893
+ setNextStepField: (fieldId: string, value: any) => void;
894
+ /**
895
+ * Set multiple fields for the next step
896
+ */
897
+ setNextStepFields: (fields: Record<string, any>) => void;
898
+ /**
899
+ * Get all workflow data
900
+ */
901
+ getAllData: () => Record<string, any>;
902
+ /**
903
+ * Get all step configurations for reference
904
+ */
905
+ getSteps: () => StepConfig[];
290
906
  }
291
907
  interface StepConfig {
292
908
  readonly id: string;
293
909
  readonly title: string;
294
910
  readonly description?: string;
295
911
  readonly formConfig: FormConfiguration;
296
- readonly validation?: StepValidationConfig;
297
- readonly conditional?: StepConditionalConfig;
298
912
  readonly allowSkip?: boolean;
299
- readonly requiredToComplete?: boolean;
300
- readonly hooks?: StepLifecycleHooks;
301
- readonly permissions?: StepPermissions;
302
- readonly isDynamic?: boolean;
303
- readonly dynamicConfig?: DynamicStepConfig;
304
913
  readonly renderer?: CustomStepRenderer;
914
+ readonly conditions?: StepConditionalBehavior;
915
+ readonly metadata?: Record<string, any>;
916
+ readonly onAfterValidation?: (stepData: Record<string, any>, helper: StepDataHelper, context: WorkflowContext) => void | Promise<void>;
305
917
  }
306
- interface StepValidationConfig {
307
- readonly validator?: (stepData: Record<string, any>, allFormData: Record<string, any>, context: WorkflowContext) => ValidationResult | Promise<ValidationResult>;
308
- readonly validateOnStepChange?: boolean;
309
- readonly blockNextIfInvalid?: boolean;
310
- }
311
- interface StepConditionalConfig {
312
- readonly condition: (formData: Record<string, any>, context: WorkflowContext) => boolean;
313
- readonly action: 'show' | 'hide' | 'skip';
314
- }
315
- type CustomStepRenderer = (props: StepConfig) => React.ReactElement;
316
- interface WorkflowPersistenceData {
317
- readonly workflowId: string;
318
- readonly currentStepIndex: number;
319
- readonly allData: Record<string, any>;
320
- readonly metadata: {
321
- readonly timestamp: number;
322
- readonly version?: string;
323
- readonly userId?: string;
324
- readonly sessionId?: string;
918
+ type CustomStepRenderer = (props: StepConfig) => React__default.ReactElement;
919
+ interface WorkflowConfig {
920
+ readonly id: string;
921
+ readonly name: string;
922
+ readonly description?: string;
923
+ readonly steps: StepConfig[];
924
+ readonly analytics?: WorkflowAnalytics;
925
+ readonly persistence?: {
926
+ adapter: any;
927
+ options?: any;
928
+ userId?: string;
325
929
  };
930
+ readonly plugins?: WorkflowPlugin[];
931
+ readonly renderConfig?: WorkflowRenderConfig;
326
932
  }
327
- interface PersistenceAdapter {
328
- readonly name: string;
329
- save(key: string, data: WorkflowPersistenceData): Promise<void>;
330
- load(key: string): Promise<WorkflowPersistenceData | null>;
331
- remove(key: string): Promise<void>;
332
- exists(key: string): Promise<boolean>;
333
- list?(pattern?: string): Promise<string[]>;
334
- }
335
- interface PersistenceConfig {
336
- readonly adapter: PersistenceAdapter;
337
- readonly key?: string;
338
- readonly debounceMs?: number;
339
- readonly autoSave?: boolean;
340
- readonly saveOnStepChange?: boolean;
341
- readonly encryptionKey?: string;
342
- readonly maxRetries?: number;
343
- readonly retryDelayMs?: number;
344
- readonly onSave?: (data: WorkflowPersistenceData) => Promise<void> | void;
345
- readonly onLoad?: (data: WorkflowPersistenceData) => Promise<void> | void;
346
- readonly onError?: (error: Error, operation: 'save' | 'load' | 'remove') => Promise<void> | void;
347
- readonly onRetry?: (attempt: number, maxRetries: number, error: Error) => Promise<void> | void;
933
+ interface WorkflowRenderConfig {
934
+ readonly stepperRenderer?: WorkflowStepperRenderer;
935
+ readonly nextButtonRenderer?: WorkflowNextButtonRenderer;
936
+ readonly previousButtonRenderer?: WorkflowPreviousButtonRenderer;
937
+ readonly skipButtonRenderer?: WorkflowSkipButtonRenderer;
348
938
  }
349
939
  interface WorkflowAnalytics {
350
940
  readonly onWorkflowStart?: (workflowId: string, context: WorkflowContext) => void;
@@ -353,58 +943,21 @@ interface WorkflowAnalytics {
353
943
  readonly onStepStart?: (stepId: string, timestamp: number, context: WorkflowContext) => void;
354
944
  readonly onStepComplete?: (stepId: string, duration: number, data: any, context: WorkflowContext) => void;
355
945
  readonly onStepSkip?: (stepId: string, reason: string, context: WorkflowContext) => void;
356
- readonly onValidationError?: (stepId: string, errors: ValidationError[], context: WorkflowContext) => void;
357
946
  readonly onError?: (error: Error, context: WorkflowContext) => void;
358
947
  }
359
- interface WorkflowOptimizations {
360
- readonly preloadNextStep?: boolean;
361
- readonly cacheValidation?: boolean;
362
- readonly virtualizeSteps?: boolean;
363
- readonly lazyLoadComponents?: boolean;
364
- readonly maxConcurrentRequests?: number;
365
- }
366
- interface WorkflowVersion {
367
- readonly version: string;
368
- readonly migrationStrategy?: (oldData: any, newConfig: any) => any;
369
- readonly compatibilityMode?: boolean;
370
- }
371
- interface WorkflowHooks {
372
- readonly onStepChange?: (from: string, to: string, context: WorkflowContext) => void;
373
- readonly onDataChange?: (data: any, context: WorkflowContext) => void;
374
- readonly onValidation?: (result: ValidationResult, context: WorkflowContext) => void;
375
- }
376
948
  interface WorkflowPlugin {
377
949
  readonly name: string;
378
950
  readonly version?: string;
379
951
  readonly install: (workflow: any) => void;
380
- readonly hooks?: WorkflowHooks;
381
952
  readonly dependencies?: string[];
382
953
  }
383
- interface WorkflowConfig {
384
- readonly id: string;
385
- readonly name: string;
386
- readonly description?: string;
387
- readonly steps: StepConfig[];
388
- readonly branches?: ConditionalBranch[];
389
- readonly navigation?: NavigationConfig;
390
- readonly persistence?: PersistenceConfig;
391
- readonly completion?: CompletionConfig;
392
- readonly analytics?: WorkflowAnalytics;
393
- readonly optimizations?: WorkflowOptimizations;
394
- readonly version?: WorkflowVersion;
395
- readonly plugins?: WorkflowPlugin[];
396
- readonly renderConfig?: WorkflowRenderConfig;
397
- }
398
- interface NavigationConfig {
399
- readonly allowBackNavigation?: boolean;
400
- readonly allowStepSkipping?: boolean;
401
- readonly showProgress?: boolean;
402
- readonly customNavigation?: boolean;
403
- }
404
- interface CompletionConfig {
405
- readonly onComplete?: (formData: Record<string, any>) => void | Promise<void>;
406
- readonly confirmBeforeSubmit?: boolean;
407
- readonly customCompletionStep?: any;
954
+ interface WorkflowComponentRendererBaseProps {
955
+ children?: React__default.ReactNode;
956
+ className?: string;
957
+ currentStep: StepConfig;
958
+ stepData: Record<string, any>;
959
+ allData: Record<string, any>;
960
+ context: WorkflowContext;
408
961
  }
409
962
  interface WorkflowStepperRendererProps {
410
963
  readonly steps: StepConfig[];
@@ -413,224 +966,496 @@ interface WorkflowStepperRendererProps {
413
966
  readonly onStepClick?: (stepIndex: number) => void;
414
967
  readonly className?: string;
415
968
  }
416
- interface WorkflowNavigationRendererProps {
417
- readonly currentStep: StepConfig;
418
- readonly context: WorkflowContext;
419
- readonly canGoNext: boolean;
420
- readonly canGoPrevious: boolean;
421
- readonly canSkip: boolean;
422
- readonly isSubmitting: boolean;
423
- readonly onNext: (event?: React.FormEvent) => void;
424
- readonly onPrevious: (event?: React.FormEvent) => void;
425
- readonly onSkip: (event?: React.FormEvent) => void;
426
- readonly onSubmit: (event?: React.FormEvent) => void;
427
- readonly className?: string;
969
+ type WorkflowNextButtonRendererProps = WorkflowComponentRendererBaseProps & {
970
+ isLastStep: boolean;
971
+ canGoNext: boolean;
972
+ isSubmitting: boolean;
973
+ onSubmit: (event?: React__default.FormEvent) => void;
974
+ };
975
+ type WorkflowPreviousButtonRendererProps = WorkflowComponentRendererBaseProps & {
976
+ canGoPrevious: boolean;
977
+ isSubmitting: boolean;
978
+ onPrevious: (event?: React__default.FormEvent) => void;
979
+ };
980
+ type WorkflowSkipButtonRendererProps = WorkflowComponentRendererBaseProps & {
981
+ canSkip: boolean;
982
+ isSubmitting: boolean;
983
+ onSkip: (event?: React__default.FormEvent) => void;
984
+ };
985
+ type WorkflowStepperRenderer = RendererChildrenFunction<WorkflowStepperRendererProps>;
986
+ type WorkflowNextButtonRenderer = RendererChildrenFunction<WorkflowNextButtonRendererProps>;
987
+ type WorkflowPreviousButtonRenderer = RendererChildrenFunction<WorkflowPreviousButtonRendererProps>;
988
+ type WorkflowSkipButtonRenderer = RendererChildrenFunction<WorkflowSkipButtonRendererProps>;
989
+ interface PerformanceMetrics {
990
+ readonly timestamp: number;
991
+ readonly duration: number;
992
+ readonly memoryUsage?: number;
993
+ readonly renderCount?: number;
994
+ readonly reRenderCount?: number;
428
995
  }
429
- type WorkflowStepperRenderer = (props: WorkflowStepperRendererProps) => React.ReactElement;
430
- type WorkflowNavigationRenderer = (props: WorkflowNavigationRendererProps) => React.ReactElement;
431
- interface WorkflowRenderConfig {
432
- readonly stepperRenderer?: WorkflowStepperRenderer;
433
- readonly navigationRenderer?: WorkflowNavigationRenderer;
996
+ interface ComponentPerformanceMetrics extends PerformanceMetrics {
997
+ readonly componentId: string;
998
+ readonly componentType: string;
999
+ readonly propsSize?: number;
1000
+ readonly childrenCount?: number;
434
1001
  }
435
- interface FormRowRendererProps {
436
- row: FormFieldRow;
437
- children: React.ReactNode;
438
- className?: string;
439
- spacing?: 'tight' | 'normal' | 'loose';
440
- alignment?: 'start' | 'center' | 'end' | 'stretch';
1002
+ interface FormPerformanceMetrics extends PerformanceMetrics {
1003
+ readonly formId: string;
1004
+ readonly fieldCount: number;
1005
+ readonly validationDuration: number;
1006
+ readonly renderDuration: number;
1007
+ readonly validationErrors: number;
441
1008
  }
442
- interface FormBodyRendererProps {
443
- formConfig: FormConfiguration;
444
- children: React.ReactNode;
445
- className?: string;
1009
+ interface WorkflowPerformanceMetrics extends PerformanceMetrics {
1010
+ readonly workflowId: string;
1011
+ readonly stepCount: number;
1012
+ readonly currentStepIndex: number;
1013
+ readonly navigationDuration: number;
1014
+ readonly persistenceDuration?: number;
1015
+ readonly conditionEvaluationDuration: number;
446
1016
  }
447
- interface FormSubmitButtonRendererProps {
448
- isSubmitting: boolean;
449
- isValid: boolean;
450
- isDirty: boolean;
451
- onSubmit: () => void;
452
- className?: string;
453
- children?: React.ReactNode;
1017
+ type MonitoringEventType = 'component_render' | 'component_update' | 'form_validation' | 'form_submission' | 'workflow_navigation' | 'workflow_persistence' | 'condition_evaluation' | 'error' | 'performance_warning';
1018
+ interface MonitoringEvent {
1019
+ readonly id: string;
1020
+ readonly type: MonitoringEventType;
1021
+ readonly timestamp: number;
1022
+ readonly source: string;
1023
+ readonly data: Record<string, any>;
1024
+ readonly metrics?: PerformanceMetrics;
1025
+ readonly severity?: 'low' | 'medium' | 'high' | 'critical';
454
1026
  }
455
- type FormRowRenderer = (props: FormRowRendererProps) => React.ReactElement;
456
- type FormBodyRenderer = (props: FormBodyRendererProps) => React.ReactElement;
457
- type FormSubmitButtonRenderer = (props: FormSubmitButtonRendererProps) => React.ReactElement;
458
- interface FormRenderConfig {
459
- readonly rowRenderer?: FormRowRenderer;
460
- readonly bodyRenderer?: FormBodyRenderer;
461
- readonly submitButtonRenderer?: FormSubmitButtonRenderer;
1027
+ interface ErrorMonitoringEvent extends MonitoringEvent {
1028
+ readonly type: 'error';
1029
+ readonly error: Error;
1030
+ readonly stack?: string;
1031
+ readonly context?: ValidationContext | WorkflowContext;
462
1032
  }
463
- interface FormConfiguration {
464
- readonly id: string;
465
- readonly schema?: any;
466
- readonly config: ril;
467
- readonly rows: FormFieldRow[];
468
- readonly allFields: FormFieldConfig[];
469
- readonly renderConfig?: FormRenderConfig;
1033
+ interface PerformanceWarningEvent extends MonitoringEvent {
1034
+ readonly type: 'performance_warning';
1035
+ readonly threshold: number;
1036
+ readonly actualValue: number;
1037
+ readonly recommendation?: string;
1038
+ }
1039
+ interface MonitoringConfig {
1040
+ readonly enabled: boolean;
1041
+ readonly enablePerformanceTracking?: boolean;
1042
+ readonly enableErrorTracking?: boolean;
1043
+ readonly enableMemoryTracking?: boolean;
1044
+ readonly performanceThresholds?: PerformanceThresholds;
1045
+ readonly sampleRate?: number;
1046
+ readonly bufferSize?: number;
1047
+ readonly flushInterval?: number;
1048
+ readonly onEvent?: (event: MonitoringEvent) => void;
1049
+ readonly onBatch?: (events: MonitoringEvent[]) => void;
1050
+ readonly onError?: (error: Error) => void;
1051
+ }
1052
+ interface PerformanceThresholds {
1053
+ readonly componentRenderTime?: number;
1054
+ readonly formValidationTime?: number;
1055
+ readonly workflowNavigationTime?: number;
1056
+ readonly memoryUsage?: number;
1057
+ readonly reRenderCount?: number;
1058
+ }
1059
+ interface MonitoringAdapter {
1060
+ readonly name: string;
1061
+ readonly version?: string;
1062
+ send: (events: MonitoringEvent[]) => Promise<void>;
1063
+ flush?: () => Promise<void>;
1064
+ configure?: (config: Record<string, any>) => void;
1065
+ }
1066
+ interface ConsoleMonitoringAdapter extends MonitoringAdapter {
1067
+ readonly name: 'console';
1068
+ readonly logLevel?: 'debug' | 'info' | 'warn' | 'error';
1069
+ }
1070
+ interface RemoteMonitoringAdapter extends MonitoringAdapter {
1071
+ readonly name: 'remote';
1072
+ readonly endpoint: string;
1073
+ readonly apiKey?: string;
1074
+ readonly headers?: Record<string, string>;
1075
+ readonly batchSize?: number;
1076
+ readonly retryAttempts?: number;
1077
+ }
1078
+ interface MonitoringContext {
1079
+ readonly sessionId: string;
1080
+ readonly userId?: string;
1081
+ readonly userAgent?: string;
1082
+ readonly url?: string;
1083
+ readonly environment: 'development' | 'production' | 'test';
1084
+ readonly version?: string;
1085
+ readonly metadata?: Record<string, any>;
1086
+ }
1087
+ interface PerformanceProfiler {
1088
+ start: (label: string, metadata?: Record<string, any>) => void;
1089
+ end: (label: string) => PerformanceMetrics | null;
1090
+ mark: (name: string) => void;
1091
+ measure: (name: string, startMark: string, endMark?: string) => number;
1092
+ getMetrics: (label: string) => PerformanceMetrics | null;
1093
+ getAllMetrics: () => Record<string, PerformanceMetrics>;
1094
+ clear: (label?: string) => void;
1095
+ }
1096
+ interface EnhancedWorkflowAnalytics extends WorkflowAnalytics {
1097
+ readonly monitoring?: MonitoringConfig;
1098
+ readonly onPerformanceWarning?: (event: PerformanceWarningEvent) => void;
1099
+ readonly onMemoryLeak?: (metrics: ComponentPerformanceMetrics) => void;
470
1100
  }
1101
+ interface EnhancedFormAnalytics {
1102
+ readonly onFormRender?: (metrics: FormPerformanceMetrics) => void;
1103
+ readonly onFormValidation?: (metrics: FormPerformanceMetrics) => void;
1104
+ readonly onFormSubmission?: (metrics: FormPerformanceMetrics) => void;
1105
+ readonly onFieldChange?: (fieldId: string, metrics: ComponentPerformanceMetrics) => void;
1106
+ readonly monitoring?: MonitoringConfig;
1107
+ }
1108
+
1109
+ declare function ComponentRendererWrapper<TProps = any>({ children, renderAs, renderer, name, props: baseProps, }: ComponentRendererWrapperProps<TProps>): React$1.ReactNode;
471
1110
 
472
1111
  /**
473
- * Create a Zod-based validator
474
- * @param schema - Zod schema to validate against
475
- * @returns Validator function
1112
+ * Utility for merging partial configurations into existing objects
1113
+ * Eliminates repetitive object spread operations
476
1114
  */
477
- declare const createZodValidator: <T>(schema: z.ZodSchema<T>) => ValidatorFunction;
1115
+ declare function mergeInto<T>(target: T, partial: Partial<T>): T;
478
1116
  /**
479
- * Create a custom validator from a validation function
480
- * @param validationFn - Function that returns boolean, string, or Promise
481
- * @returns Validator function
1117
+ * Validates uniqueness of identifiers and throws descriptive errors
482
1118
  */
483
- declare const createCustomValidator: (validationFn: (value: any, context: ValidationContext) => boolean | string | Promise<boolean | string>) => ValidatorFunction;
1119
+ declare function ensureUnique(ids: string[], entityName: string): void;
484
1120
  /**
485
- * Combine multiple validators
486
- * @param validators - Array of validators to combine
487
- * @param mode - 'all' (all must pass) or 'any' (at least one must pass)
488
- * @returns Combined validator function
1121
+ * Validates required fields exist in configurations
489
1122
  */
490
- declare const combineValidators: (validators: ValidatorFunction[], mode?: "all" | "any") => ValidatorFunction;
1123
+ declare function validateRequired<T>(items: T[], requiredFields: (keyof T)[], entityName: string): void;
491
1124
  /**
492
- * Create a conditional validator that only runs when condition is met
493
- * @param condition - Function to determine if validation should run
494
- * @param validator - Validator to run when condition is true
495
- * @returns Conditional validator function
1125
+ * Auto-generates IDs when not provided
496
1126
  */
497
- declare const createConditionalValidator: (condition: (value: any, context: ValidationContext) => boolean, validator: ValidatorFunction) => ValidatorFunction;
1127
+ declare class IdGenerator {
1128
+ private counters;
1129
+ next(prefix: string): string;
1130
+ reset(prefix?: string): void;
1131
+ }
498
1132
  /**
499
- * Common validation patterns
1133
+ * Polymorphic helper for handling single items or arrays
500
1134
  */
501
- declare const commonValidators: {
502
- /**
503
- * Required field validator
504
- */
505
- required: (message?: string) => ValidatorFunction;
1135
+ declare function normalizeToArray<T>(input: T | T[]): T[];
1136
+ /**
1137
+ * Deep clone utility for configuration objects
1138
+ */
1139
+ declare function deepClone<T>(obj: T): T;
1140
+ /**
1141
+ * Generic configuration merger with type safety
1142
+ */
1143
+ declare function configureObject<T>(target: T, updates: Partial<T>, allowedKeys?: (keyof T)[]): T;
1144
+
1145
+ declare function resolveRendererChildren<TProps>(children: React.ReactNode | RendererChildrenFunction<TProps> | undefined, props: TProps): React.ReactNode;
1146
+
1147
+ /**
1148
+ * @fileoverview Clean validation utilities for Standard Schema
1149
+ *
1150
+ * This module provides utility functions for working with validation results
1151
+ * and managing validation contexts using Standard Schema exclusively.
1152
+ */
1153
+
1154
+ /**
1155
+ * Checks whether a value is considered "empty" for validation purposes.
1156
+ *
1157
+ * Handles: `undefined`, `null`, empty string, whitespace-only string,
1158
+ * empty array, and empty plain object.
1159
+ *
1160
+ * @returns `true` if the value is empty
1161
+ */
1162
+ declare function isEmptyValue(value: unknown): boolean;
1163
+ /**
1164
+ * Creates a validation result object
1165
+ *
1166
+ * @param isValid - Whether the validation passed
1167
+ * @param errors - Array of validation errors (empty if valid)
1168
+ * @returns A complete ValidationResult object
1169
+ *
1170
+ * @example
1171
+ * ```typescript
1172
+ * const result = createValidationResult(false, [
1173
+ * { message: 'Email is required', code: 'REQUIRED' }
1174
+ * ]);
1175
+ * ```
1176
+ */
1177
+ declare function createValidationResult(isValid: boolean, errors?: ValidationError[]): ValidationResult;
1178
+ /**
1179
+ * Creates a successful validation result
1180
+ *
1181
+ * @returns A successful ValidationResult with no errors
1182
+ *
1183
+ * @example
1184
+ * ```typescript
1185
+ * const success = createSuccessResult();
1186
+ * ```
1187
+ */
1188
+ declare function createSuccessResult(): ValidationResult;
1189
+ /**
1190
+ * Creates a failed validation result with a single error
1191
+ *
1192
+ * @param message - The error message
1193
+ * @param code - Optional error code
1194
+ * @param path - Optional field path
1195
+ * @returns A failed ValidationResult
1196
+ *
1197
+ * @example
1198
+ * ```typescript
1199
+ * const error = createErrorResult('Email is invalid', 'INVALID_EMAIL');
1200
+ * ```
1201
+ */
1202
+ declare function createErrorResult(message: string, code?: string, path?: string): ValidationResult;
1203
+ /**
1204
+ * Creates a validation context object
1205
+ *
1206
+ * @param options - Context configuration options
1207
+ * @returns A complete ValidationContext object
1208
+ *
1209
+ * @example
1210
+ * ```typescript
1211
+ * const context = createValidationContext({
1212
+ * fieldId: 'email',
1213
+ * formId: 'registration',
1214
+ * allFormData: { email: 'test@example.com', name: 'John' }
1215
+ * });
1216
+ * ```
1217
+ */
1218
+ declare function createValidationContext(options?: Partial<ValidationContext>): ValidationContext;
1219
+
1220
+ /**
1221
+ * Built-in validators implementing Standard Schema interface
1222
+ * All RilayKit validators now implement Standard Schema for consistency
1223
+ */
1224
+
1225
+ /**
1226
+ * Required field validator - Standard Schema implementation
1227
+ */
1228
+ declare function required(message?: string): StandardSchemaV1<any>;
1229
+ /**
1230
+ * Email validation - Standard Schema implementation
1231
+ */
1232
+ declare function email(message?: string): StandardSchemaV1<string>;
1233
+ /**
1234
+ * URL validation - Standard Schema implementation
1235
+ */
1236
+ declare function url(message?: string): StandardSchemaV1<string>;
1237
+ /**
1238
+ * Minimum length validation - Standard Schema implementation
1239
+ */
1240
+ declare function minLength(min: number, message?: string): StandardSchemaV1<string>;
1241
+ /**
1242
+ * Maximum length validation - Standard Schema implementation
1243
+ */
1244
+ declare function maxLength(max: number, message?: string): StandardSchemaV1<string>;
1245
+ /**
1246
+ * Pattern validation - Standard Schema implementation
1247
+ */
1248
+ declare function pattern(regex: RegExp, message?: string): StandardSchemaV1<string>;
1249
+ /**
1250
+ * Number validation - Standard Schema implementation
1251
+ */
1252
+ declare function number(message?: string): StandardSchemaV1<number>;
1253
+ /**
1254
+ * Minimum value validation - Standard Schema implementation
1255
+ */
1256
+ declare function min(minValue: number, message?: string): StandardSchemaV1<number>;
1257
+ /**
1258
+ * Maximum value validation - Standard Schema implementation
1259
+ */
1260
+ declare function max(maxValue: number, message?: string): StandardSchemaV1<number>;
1261
+ /**
1262
+ * Custom validator - Standard Schema implementation
1263
+ */
1264
+ declare function custom<T>(fn: (value: T) => boolean, message?: string): StandardSchemaV1<T>;
1265
+ /**
1266
+ * Async validator - Standard Schema implementation
1267
+ */
1268
+ declare function async<T>(fn: (value: T) => Promise<boolean>, message?: string): StandardSchemaV1<T>;
1269
+ /**
1270
+ * Utility to combine multiple Standard Schema validators
1271
+ * This creates a new Standard Schema that runs all validations
1272
+ */
1273
+ declare function combine<T>(...schemas: StandardSchemaV1<T>[]): StandardSchemaV1<T>;
1274
+
1275
+ /**
1276
+ * Unified validation utilities for Standard Schema only
1277
+ * These replace the old validator-based system with a clean Standard Schema approach
1278
+ */
1279
+
1280
+ /**
1281
+ * Checks if a value implements the Standard Schema interface
1282
+ */
1283
+ declare function isStandardSchema(value: any): value is StandardSchema;
1284
+ /**
1285
+ * Validates a value using a Standard Schema
1286
+ */
1287
+ declare function validateWithStandardSchema<T extends StandardSchema>(schema: T, value: unknown): Promise<ValidationResult>;
1288
+ /**
1289
+ * Utility to extract input type from Standard Schema at runtime (for debugging)
1290
+ */
1291
+ declare function getSchemaInfo(schema: StandardSchema): {
1292
+ vendor: string;
1293
+ version: number;
1294
+ hasTypes: boolean;
1295
+ };
1296
+ /**
1297
+ * Type guard to check if a schema has type information
1298
+ */
1299
+ declare function hasSchemaTypes<T extends StandardSchema>(schema: T): schema is T & {
1300
+ '~standard': {
1301
+ types: NonNullable<T['~standard']['types']>;
1302
+ };
1303
+ };
1304
+ /**
1305
+ * Validates a value using unified validation config
1306
+ * Handles single schemas, arrays of schemas, and combines results
1307
+ */
1308
+ declare function validateWithUnifiedConfig<T>(config: FieldValidationConfig<T>, value: T, _context: ValidationContext): Promise<ValidationResult>;
1309
+ /**
1310
+ * Validates form data using unified validation config
1311
+ */
1312
+ declare function validateFormWithUnifiedConfig<T extends Record<string, any>>(config: FormValidationConfig<T>, formData: T, _context: ValidationContext): Promise<ValidationResult>;
1313
+ /**
1314
+ * Checks if a field validation config has any validation rules
1315
+ */
1316
+ declare function hasUnifiedValidation(config: FieldValidationConfig | FormValidationConfig): boolean;
1317
+ /**
1318
+ * Combines multiple Standard Schemas into a single schema
1319
+ * This is useful for combining built-in validators with external schemas
1320
+ */
1321
+ declare function combineSchemas<T>(...schemas: StandardSchemaV1<T>[]): StandardSchemaV1<T>;
1322
+ /**
1323
+ * Utility to create a Standard Schema from any validation function
1324
+ * This helps migrate existing validators to Standard Schema
1325
+ */
1326
+ declare function createStandardValidator<T>(validateFn: (value: T, context?: ValidationContext) => ValidationResult | Promise<ValidationResult>, vendor?: string): StandardSchemaV1<T>;
1327
+ /**
1328
+ * Type guard to check if value is a Standard Schema or array of Standard Schemas
1329
+ */
1330
+ declare function isValidationRule(value: any): value is StandardSchema | StandardSchema[];
1331
+ /**
1332
+ * Normalizes validation config to always return an array of Standard Schemas
1333
+ */
1334
+ declare function normalizeValidationRules<T>(validate: StandardSchema<T> | StandardSchema<T>[] | undefined): StandardSchema<T>[];
1335
+
1336
+ /**
1337
+ * Core monitoring system for Rilay
1338
+ * Tracks performance metrics, events, and errors across forms and workflows
1339
+ */
1340
+ declare class RilayMonitor {
1341
+ private config;
1342
+ private context;
1343
+ private adapters;
1344
+ private eventBuffer;
1345
+ private flushTimer?;
1346
+ private profiler;
1347
+ constructor(config: MonitoringConfig, context?: Partial<MonitoringContext>);
506
1348
  /**
507
- * Email validation
1349
+ * Add a monitoring adapter
508
1350
  */
509
- email: (message?: string) => ValidatorFunction;
1351
+ addAdapter(adapter: MonitoringAdapter): void;
510
1352
  /**
511
- * Minimum length validation
1353
+ * Remove a monitoring adapter
512
1354
  */
513
- minLength: (min: number, message?: string) => ValidatorFunction;
1355
+ removeAdapter(adapterName: string): void;
514
1356
  /**
515
- * Maximum length validation
1357
+ * Track a monitoring event
516
1358
  */
517
- maxLength: (max: number, message?: string) => ValidatorFunction;
1359
+ track(type: MonitoringEventType, source: string, data: Record<string, any>, metrics?: PerformanceMetrics, severity?: 'low' | 'medium' | 'high' | 'critical'): void;
518
1360
  /**
519
- * Pattern/regex validation
1361
+ * Track an error
520
1362
  */
521
- pattern: (regex: RegExp, message?: string) => ValidatorFunction;
1363
+ trackError(error: Error, source: string, context?: any): void;
522
1364
  /**
523
- * Number range validation
1365
+ * Get the performance profiler
524
1366
  */
525
- numberRange: (min?: number, max?: number, message?: string) => ValidatorFunction;
1367
+ getProfiler(): PerformanceProfiler;
526
1368
  /**
527
- * URL validation
1369
+ * Update monitoring context
528
1370
  */
529
- url: (message?: string) => ValidatorFunction;
1371
+ updateContext(updates: Partial<MonitoringContext>): void;
530
1372
  /**
531
- * Phone number validation (basic)
1373
+ * Flush all buffered events
532
1374
  */
533
- phoneNumber: (message?: string) => ValidatorFunction;
1375
+ flush(): Promise<void>;
534
1376
  /**
535
- * Custom async validation with debouncing
1377
+ * Destroy the monitor and clean up resources
536
1378
  */
537
- asyncValidation: (asyncFn: (value: any, context: ValidationContext) => Promise<boolean | string>, debounceMs?: number) => ValidatorFunction;
538
- };
1379
+ destroy(): Promise<void>;
1380
+ private startFlushTimer;
1381
+ private checkPerformanceThresholds;
1382
+ private createPerformanceWarning;
1383
+ }
1384
+ /**
1385
+ * Initialize global monitoring
1386
+ */
1387
+ declare function initializeMonitoring(config: MonitoringConfig, context?: Partial<MonitoringContext>): RilayMonitor;
539
1388
  /**
540
- * Utility to create validation result
541
- * @param isValid - Whether validation passed
542
- * @param errors - Array of errors (optional)
543
- * @param warnings - Array of warnings (optional)
544
- * @returns ValidationResult object
1389
+ * Get the global monitor instance
545
1390
  */
546
- declare const createValidationResult: (isValid: boolean, errors?: ValidationError[], warnings?: ValidationError[]) => ValidationResult;
1391
+ declare function getGlobalMonitor(): RilayMonitor | null;
547
1392
  /**
548
- * Utility to create validation error
549
- * @param code - Error code
550
- * @param message - Error message
551
- * @param path - Error path (optional)
552
- * @returns ValidationError object
1393
+ * Destroy global monitoring
553
1394
  */
554
- declare const createValidationError: (code: string, message: string, path?: string[]) => ValidationError;
1395
+ declare function destroyGlobalMonitoring(): Promise<void>;
555
1396
 
556
1397
  /**
557
- * LocalStorage persistence adapter
558
- * Perfect for client-side persistence across browser sessions
1398
+ * Console monitoring adapter
1399
+ * Logs events to the browser console
559
1400
  */
560
- declare class LocalStorageAdapter implements PersistenceAdapter {
561
- readonly name = "localStorage";
562
- save(key: string, data: WorkflowPersistenceData): Promise<void>;
563
- load(key: string): Promise<WorkflowPersistenceData | null>;
564
- remove(key: string): Promise<void>;
565
- exists(key: string): Promise<boolean>;
566
- list(pattern?: string): Promise<string[]>;
567
- }
568
- /**
569
- * SessionStorage persistence adapter
570
- * Perfect for temporary persistence within a single browser session
571
- */
572
- declare class SessionStorageAdapter implements PersistenceAdapter {
573
- readonly name = "sessionStorage";
574
- save(key: string, data: WorkflowPersistenceData): Promise<void>;
575
- load(key: string): Promise<WorkflowPersistenceData | null>;
576
- remove(key: string): Promise<void>;
577
- exists(key: string): Promise<boolean>;
578
- list(pattern?: string): Promise<string[]>;
579
- }
580
- /**
581
- * In-Memory persistence adapter
582
- * Perfect for testing or temporary workflows
583
- */
584
- declare class MemoryAdapter implements PersistenceAdapter {
585
- readonly name = "memory";
586
- private storage;
587
- save(key: string, data: WorkflowPersistenceData): Promise<void>;
588
- load(key: string): Promise<WorkflowPersistenceData | null>;
589
- remove(key: string): Promise<void>;
590
- exists(key: string): Promise<boolean>;
591
- list(pattern?: string): Promise<string[]>;
592
- clear(): void;
1401
+ declare class ConsoleAdapter implements ConsoleMonitoringAdapter {
1402
+ readonly name = "console";
1403
+ readonly logLevel: 'debug' | 'info' | 'warn' | 'error';
1404
+ constructor(logLevel?: 'debug' | 'info' | 'warn' | 'error');
1405
+ send(events: MonitoringEvent[]): Promise<void>;
1406
+ private logEvent;
1407
+ private shouldLog;
593
1408
  }
594
1409
  /**
595
- * Composite adapter that can use multiple adapters with fallback
596
- * Perfect for robust persistence with primary/backup strategies
1410
+ * Remote monitoring adapter
1411
+ * Sends events to a remote endpoint
597
1412
  */
598
- declare class CompositeAdapter implements PersistenceAdapter {
599
- private primary;
600
- private fallbacks;
601
- readonly name = "composite";
602
- constructor(primary: PersistenceAdapter, fallbacks?: PersistenceAdapter[]);
603
- save(key: string, data: WorkflowPersistenceData): Promise<void>;
604
- load(key: string): Promise<WorkflowPersistenceData | null>;
605
- remove(key: string): Promise<void>;
606
- exists(key: string): Promise<boolean>;
607
- list(pattern?: string): Promise<string[]>;
1413
+ declare class RemoteAdapter implements RemoteMonitoringAdapter {
1414
+ readonly name = "remote";
1415
+ readonly endpoint: string;
1416
+ readonly apiKey?: string;
1417
+ readonly headers: Record<string, string>;
1418
+ readonly batchSize: number;
1419
+ readonly retryAttempts: number;
1420
+ private eventQueue;
1421
+ private isProcessing;
1422
+ constructor(config: {
1423
+ endpoint: string;
1424
+ apiKey?: string;
1425
+ headers?: Record<string, string>;
1426
+ batchSize?: number;
1427
+ retryAttempts?: number;
1428
+ });
1429
+ send(events: MonitoringEvent[]): Promise<void>;
1430
+ flush(): Promise<void>;
1431
+ configure(config: Record<string, any>): void;
1432
+ private processQueue;
1433
+ private sendBatch;
1434
+ private delay;
608
1435
  }
609
-
610
1436
  /**
611
- * Utility functions to create persistence configurations easily
1437
+ * Local storage adapter for offline support
612
1438
  */
613
- declare const persistence: {
614
- /**
615
- * Create a localStorage-based persistence configuration
616
- */
617
- localStorage(options?: Partial<PersistenceConfig>): PersistenceConfig;
618
- /**
619
- * Create a sessionStorage-based persistence configuration
620
- */
621
- sessionStorage(options?: Partial<PersistenceConfig>): PersistenceConfig;
622
- /**
623
- * Create an in-memory persistence configuration (for testing)
624
- */
625
- memory(options?: Partial<PersistenceConfig>): PersistenceConfig;
626
- /**
627
- * Create a custom persistence configuration
628
- */
629
- custom(adapter: PersistenceAdapter, options?: Partial<PersistenceConfig>): PersistenceConfig;
630
- };
1439
+ declare class LocalStorageAdapter implements MonitoringAdapter {
1440
+ readonly name = "localStorage";
1441
+ private readonly storageKey;
1442
+ private readonly maxEvents;
1443
+ constructor(maxEvents?: number);
1444
+ send(events: MonitoringEvent[]): Promise<void>;
1445
+ flush(): Promise<void>;
1446
+ getStoredEvents(): MonitoringEvent[];
1447
+ clearStoredEvents(): void;
1448
+ getEventCount(): number;
1449
+ }
631
1450
  /**
632
- * Utility to create persistence configurations with retry logic
1451
+ * Development adapter that provides detailed logging
633
1452
  */
634
- declare function createResilientPersistence(primary: PersistenceAdapter, fallback?: PersistenceAdapter, options?: Partial<PersistenceConfig>): PersistenceConfig;
1453
+ declare class DevelopmentAdapter implements MonitoringAdapter {
1454
+ readonly name = "development";
1455
+ private readonly console;
1456
+ send(events: MonitoringEvent[]): Promise<void>;
1457
+ private logPerformanceSummary;
1458
+ private logErrorSummary;
1459
+ }
635
1460
 
636
- export { type CompletionConfig, type ComponentConfig, type ComponentOptions, type ComponentRenderProps, type ComponentRenderer, type ComponentType, CompositeAdapter, type ConditionalBranch, type ConditionalConfig, type CustomStepRenderer, type DynamicStepConfig, type FormBodyRenderer, type FormBodyRendererProps, type FormConfiguration, type FormFieldConfig, type FormFieldRow, type FormRenderConfig, type FormRowRenderer, type FormRowRendererProps, type FormSubmitButtonRenderer, type FormSubmitButtonRendererProps, type InputType, type LayoutType, LocalStorageAdapter, MemoryAdapter, type NavigationConfig, type PersistenceAdapter, type PersistenceConfig, type RetryPolicy, type RilayLicenseConfig, SessionStorageAdapter, type StepConditionalConfig, type StepConfig, type StepLifecycleHooks, type StepPermissions, type StepValidationConfig, type ValidationConfig, type ValidationContext, type ValidationError, type ValidationResult, type ValidationWarning, type ValidatorFunction, type WorkflowAnalytics, type WorkflowConfig, type WorkflowContext, type WorkflowHooks, type WorkflowNavigationRenderer, type WorkflowNavigationRendererProps, type WorkflowOptimizations, type WorkflowPersistenceData, type WorkflowPlugin, type WorkflowRenderConfig, type WorkflowStepperRenderer, type WorkflowStepperRendererProps, type WorkflowVersion, combineValidators, commonValidators, createConditionalValidator, createCustomValidator, createResilientPersistence, createValidationError, createValidationResult, createZodValidator, persistence, ril };
1461
+ export { type ComponentBuilderMetadata, type ComponentConfig, type ComponentPerformanceMetrics, type ComponentRenderProps, type ComponentRenderPropsV2, type ComponentRenderer, type ComponentRendererBaseProps, ComponentRendererWrapper, type ComponentRendererWrapperProps, type ConditionBuilder as Condition, type ConditionBuilder, type ConditionConfig, ConditionDependencyGraph, type ConditionEvaluator, type ConditionOperator, type ConditionValue, type ConditionalBehavior, ConsoleAdapter, type ConsoleMonitoringAdapter, type CustomStepRenderer, DevelopmentAdapter, type EnhancedFormAnalytics, type EnhancedWorkflowAnalytics, type ErrorMonitoringEvent, type FieldActions, type FieldConditions, type FieldContext, type FieldRenderer, type FieldRendererProps, type FieldRendererPropsV2, type FieldSchemaDefinition, type FieldState, type FieldValidationConfig, type FieldValidator, type FormActions, type FormBodyRenderer, type FormBodyRendererProps, type FormComponentRendererProps, type FormConfiguration, type FormContextValue, type FormFieldConfig, type FormFieldRow, type FormPerformanceMetrics, type FormRenderConfig, type FormRepeatableRow, type FormRowEntry, type FormRowRenderer, type FormRowRendererProps, type FormState, type FormSubmitButtonRenderer, type FormSubmitButtonRendererProps, type FormSubmitButtonRendererPropsV2, type FormValidationConfig, type FormValidator, IdGenerator, type InferInput, type InferOutput, LocalStorageAdapter, type LogicalOperator, type MonitoringAdapter, type MonitoringConfig, type MonitoringContext, type MonitoringEvent, type MonitoringEventType, type PerformanceMetrics, type PerformanceProfiler, type PerformanceThresholds, type PerformanceWarningEvent, type PropertyEditorDefinition, type PropertyEditorProps, RemoteAdapter, type RemoteMonitoringAdapter, type RendererChildrenFunction, type RepeatableFieldConfig, type RepeatableFieldItem, type RepeatableFieldRenderer, type RepeatableFieldRendererProps, type RepeatableItemRenderer, type RepeatableItemRendererProps, type RilayInstance, type RilayLicenseConfig, RilayMonitor, type StandardSchema, type StepConditionalBehavior, type StepConfig, type StepDataHelper, type ValidationContext, type ValidationError, type ValidationResult, type ValidationState, type WorkflowAnalytics, type WorkflowButtonRendererPropsV2, type WorkflowComponentRendererBaseProps, type WorkflowConfig, type WorkflowContext, type WorkflowNavigationState, type WorkflowNextButtonRenderer, type WorkflowNextButtonRendererProps, type WorkflowPerformanceMetrics, type WorkflowPlugin, type WorkflowPreviousButtonRenderer, type WorkflowPreviousButtonRendererProps, type WorkflowProgressState, type WorkflowRenderConfig, type WorkflowSkipButtonRenderer, type WorkflowSkipButtonRendererProps, type WorkflowStepContext, type WorkflowStepState, type WorkflowStepperRenderer, type WorkflowStepperRendererProps, async, combine, combineSchemas, configureObject, createErrorResult, createStandardValidator, createSuccessResult, createValidationContext, createValidationResult, custom, deepClone, destroyGlobalMonitoring, email, ensureUnique, evaluateCondition, extractAllDependencies, extractConditionDependencies, getGlobalMonitor, getSchemaInfo, hasSchemaTypes, hasUnifiedValidation, initializeMonitoring, isEmptyValue, isStandardSchema, isValidationRule, max, maxLength, mergeInto, min, minLength, normalizeToArray, normalizeValidationRules, number, pattern, required, resolveRendererChildren, ril, url, validateFormWithUnifiedConfig, validateRequired, validateWithStandardSchema, validateWithUnifiedConfig, when };