@finsweet/webflow-apps-utils 1.0.4 → 1.0.5

package/dist/stores/docs/Form.mdx

@@ -1,542 +0,0 @@
-# Form Validation System
-
-A comprehensive form validation system built with Svelte stores and Zod for type-safe form handling in Webflow apps.
-
-## Overview
-
-The form validation system provides:
-
-- Type-safe form state management with Zod validation
-- Unique instance name generation for Webflow components
-- Real-time validation with error handling
-- Form registry for managing multiple forms
-- Class name sanitization for HTML compliance
-
-## Core Classes and Functions
-
-### FormValidator Class
-
-The main class for creating and managing form validation state.
-
-```typescript
-import { FormValidator } from '$lib/stores/forms';
-
-// Define your form data structure
-interface MyFormData {
-	name: string;
-	instance: string;
-	class: string;
-}
-
-// Create a form validator
-const formValidator = new FormValidator<MyFormData>(
-	'my-form-id',
-	{
-		name: 'My Component',
-		instance: 'fs-component',
-		class: 'fs-component'
-	},
-	{
-		existingInstances: ['fs-existing-1', 'fs-existing-2']
-	}
-);
-```
-
-#### Constructor Parameters
-
-- `identifier: string` - Unique identifier for the form (used in global registry)
-- `initialValues: T` - Initial form values
-- `options.existingInstances?: string[]` - Array of existing instance names for uniqueness validation
-
-**Note:** Class validation is enabled by default. Use `enableClassValidation(false)` to disable it if your component doesn't require CSS classes.
-
-### Static Methods
-
-#### generateNames()
-
-Generates unique names, instances, and class names based on existing instances:
-
-```typescript
-const generated = FormValidator.generateNames(
-	['fs-slider-1', 'fs-slider-2'], // existing instances
-	'slider', // solution name
-	'Slider Component' // display name
-);
-
-// Returns:
-// {
-//   name: 'Slider Component 3',
-//   instance: 'fs-slider-3',
-//   class: 'fs-slider-3'
-// }
-```
-
-#### sanitizeClassName()
-
-Cleans up class names to ensure HTML compliance:
-
-```typescript
-const cleaned = FormValidator.sanitizeClassName('my/invalid class-name!');
-// Returns: 'my-invalid-class-name'
-```
-
-### Instance Methods
-
-#### setField()
-
-Updates a single form field:
-
-```typescript
-formValidator.setField('name', 'New Component Name');
-```
-
-#### setFields()
-
-Updates multiple form fields at once:
-
-```typescript
-formValidator.setFields({
-	name: 'New Name',
-	instance: 'fs-new-instance'
-});
-```
-
-#### validateWithInstances()
-
-Updates the list of existing instances and re-validates:
-
-```typescript
-formValidator.validateWithInstances(['fs-new-1', 'fs-new-2']);
-```
-
-#### ignoreInstanceValidation()
-
-Temporarily ignores a specific instance during validation (useful for edit mode):
-
-```typescript
-formValidator.ignoreInstanceValidation('fs-current-instance', existingInstances);
-```
-
-#### reset()
-
-Resets the form to its initial state:
-
-```typescript
-formValidator.reset();
-```
-
-#### enableClassValidation()
-
-Enables or disables class name validation dynamically:
-
-```typescript
-// Disable class validation (useful for certain component types)
-formValidator.enableClassValidation(false);
-
-// Re-enable class validation
-formValidator.enableClassValidation(true);
-```
-
-#### getState()
-
-Gets the current form state:
-
-```typescript
-const state = formValidator.getState();
-console.log(state.isValid, state.errors, state.values);
-```
-
-#### setSubmitting()
-
-Sets the form submission state:
-
-```typescript
-formValidator.setSubmitting(true);
-// ... perform submission
-formValidator.setSubmitting(false);
-```
-
-## Form State Structure
-
-The form state contains:
-
-```typescript
-interface FormState<T> {
-	values: T; // Current form values
-	errors: Record<keyof T, string[]>; // Validation errors by field
-	touched: Record<keyof T, boolean>; // Fields that have been interacted with
-	isValid: boolean; // Overall form validity
-	isDirty: boolean; // Whether form has been modified
-	isSubmitting: boolean; // Submission state
-}
-```
-
-## Global Form Registry
-
-The system maintains a global registry of all forms for cross-component access.
-
-### getFormById()
-
-Retrieve a form instance by its identifier:
-
-```typescript
-import { getFormById } from '$lib/stores/forms';
-
-const form = getFormById('my-form-id');
-if (form) {
-	console.log(form.getState());
-}
-```
-
-### isFormValid()
-
-Check if a specific form is valid:
-
-```typescript
-import { isFormValid } from '$lib/stores/forms';
-
-if (isFormValid('my-form-id')) {
-	console.log('Form is valid!');
-}
-```
-
-### getFormErrors()
-
-Get error messages for a specific form:
-
-```typescript
-import { getFormErrors } from '$lib/stores/forms';
-
-const errors = getFormErrors('my-form-id');
-console.log(errors);
-```
-
-### resetForm()
-
-Reset a form by its identifier:
-
-```typescript
-import { resetForm } from '$lib/stores/forms';
-
-resetForm('my-form-id');
-```
-
-## Svelte Integration
-
-### Using in Svelte Components
-
-```svelte
-<script lang="ts">
-	import { FormValidator } from '$lib/stores/forms';
-
-	interface ComponentForm {
-		name: string;
-		instance: string;
-		class: string;
-	}
-
-	// Create form validator
-	const formValidator = new FormValidator<ComponentForm>('component-form', {
-		name: '',
-		instance: '',
-		class: ''
-	});
-
-	// Subscribe to form state
-	$: formState = formValidator.form;
-</script>
-
-<form>
-	<input
-		type="text"
-		bind:value={$formState.values.name}
-		on:input={(e) => formValidator.setField('name', e.target.value)}
-		class:error={$formState.errors.name?.length > 0}
-	/>
-
-	{#if $formState.errors.name?.length > 0}
-		<div class="error-message">
-			{$formState.errors.name[0]}
-		</div>
-	{/if}
-
-	<button type="submit" disabled={!$formState.isValid || $formState.isSubmitting}>
-		{$formState.isSubmitting ? 'Saving...' : 'Save'}
-	</button>
-</form>
-```
-
-### Form Subscription Helper
-
-For components that need to subscribe to form state changes:
-
-```typescript
-import { createFormSubscription } from '$lib/stores/forms';
-
-const formSubscription = createFormSubscription('my-form-id');
-
-// Use in component
-$: formState = formSubscription;
-
-// Cleanup when component is destroyed
-onDestroy(() => {
-	formSubscription.destroy();
-});
-```
-
-## Validation Rules
-
-The system includes built-in validation for Webflow component forms:
-
-### Name Field
-
-- Required (minimum 1 character)
-
-### Instance Field
-
-- Required (minimum 1 character)
-- Must be unique across existing instances
-- Case-insensitive uniqueness check
-
-### Class Field
-
-- Required by default (minimum 1 character when validation is enabled)
-- Must contain only letters, numbers, underscores, and hyphens
-- Automatically sanitized with `sanitizeClassName()`
-- Can be disabled using `enableClassValidation(false)` for components that don't require CSS classes
-
-## Global Loading States
-
-The module also exports global loading state stores:
-
-```typescript
-import { isAddingOrUpdating, loadingSelectedElement } from '$lib/stores/forms';
-
-// Track if form is being added or updated to Canvas
-$: $isAddingOrUpdating = true;
-
-// Track if selected element is loading
-$: $loadingSelectedElement = true;
-```
-
-## Dynamic Class Validation
-
-The form validator supports enabling or disabling class name validation based on your component's requirements. This is useful for components that don't require CSS classes or when you want to allow more flexible class naming.
-
-### When to Disable Class Validation
-
-- Components that only use inline styles
-- Third-party integrations that don't require CSS classes
-- Temporary or test components
-- Components where class names are generated programmatically
-
-### Usage Examples
-
-```typescript
-// Create form with class validation enabled (default)
-const formValidator = new FormValidator('component-form', initialValues);
-
-// Disable class validation for a component that doesn't need CSS
-formValidator.enableClassValidation(false);
-
-// Re-enable class validation if needed later
-formValidator.enableClassValidation(true);
-```
-
-### Conditional Class Validation
-
-```svelte
-<script lang="ts">
-	import { FormValidator } from '$lib/stores/forms';
-
-	export let componentType: 'styled' | 'utility' | 'inline';
-
-	const formValidator = new FormValidator('dynamic-form', initialValues);
-
-	// Disable class validation for inline components
-	$: {
-		const needsClassValidation = componentType === 'styled' || componentType === 'utility';
-		formValidator.enableClassValidation(needsClassValidation);
-	}
-</script>
-```
-
-### Component-Specific Validation
-
-```typescript
-// Different validation rules for different component types
-const createFormForComponent = (componentType: string, initialValues: FormData) => {
-	const formValidator = new FormValidator(`${componentType}-form`, initialValues);
-
-	// Disable class validation for certain component types
-	const noClassComponents = ['embed', 'script', 'raw-html'];
-	if (noClassComponents.includes(componentType)) {
-		formValidator.enableClassValidation(false);
-	}
-
-	return formValidator;
-};
-```
-
-## Best Practices
-
-### 1. Unique Form Identifiers
-
-Always use unique identifiers for each form to prevent conflicts:
-
-```typescript
-const formValidator = new FormValidator(`${componentType}-${componentId}-form`, initialValues);
-```
-
-### 2. Handle Existing Instances
-
-Always provide existing instances for proper uniqueness validation:
-
-```typescript
-const formValidator = new FormValidator('form-id', initialValues, {
-	existingInstances: getAllExistingInstances()
-});
-```
-
-### 3. Edit Mode Handling
-
-Use `ignoreInstanceValidation()` when editing existing components:
-
-```typescript
-if (isEditMode) {
-	formValidator.ignoreInstanceValidation(currentInstance, existingInstances);
-}
-```
-
-### 4. Cleanup
-
-Always clean up form subscriptions to prevent memory leaks:
-
-```typescript
-onDestroy(() => {
-	formSubscription.destroy();
-});
-```
-
-## Example: Complete Component Form
-
-```svelte
-<script lang="ts">
-	import { onDestroy } from 'svelte';
-	import { FormValidator } from '$lib/stores/forms';
-
-	export let existingInstances: string[] = [];
-	export let isEditMode = false;
-	export let currentInstance = '';
-	export let componentType: 'styled' | 'utility' | 'embed' = 'styled';
-
-	interface SliderForm {
-		name: string;
-		instance: string;
-		class: string;
-	}
-
-	// Generate initial values
-	const initialValues = isEditMode
-		? { name: currentInstance, instance: currentInstance, class: currentInstance }
-		: FormValidator.generateNames(existingInstances, 'slider', 'Slider Component');
-
-	// Create form validator
-	const formValidator = new FormValidator<SliderForm>('slider-form', initialValues, {
-		existingInstances
-	});
-
-	// Handle edit mode
-	if (isEditMode) {
-		formValidator.ignoreInstanceValidation(currentInstance, existingInstances);
-	}
-
-	// Handle class validation based on component type
-	$: {
-		const needsClassValidation = componentType !== 'embed';
-		formValidator.enableClassValidation(needsClassValidation);
-	}
-
-	// Subscribe to form state
-	$: formState = formValidator.form;
-
-	async function handleSubmit() {
-		if (!$formState.isValid) return;
-
-		formValidator.setSubmitting(true);
-
-		try {
-			// Submit form data
-			await submitToWebflow($formState.values);
-		} finally {
-			formValidator.setSubmitting(false);
-		}
-	}
-</script>
-
-<form on:submit|preventDefault={handleSubmit}>
-	<div class="field">
-		<label for="name">Component Name</label>
-		<input
-			id="name"
-			type="text"
-			bind:value={$formState.values.name}
-			on:input={(e) => formValidator.setField('name', e.target.value)}
-			class:error={$formState.errors.name?.length > 0}
-		/>
-		{#if $formState.errors.name?.length > 0}
-			<span class="error">{$formState.errors.name[0]}</span>
-		{/if}
-	</div>
-
-	<div class="field">
-		<label for="instance">Instance Name</label>
-		<input
-			id="instance"
-			type="text"
-			bind:value={$formState.values.instance}
-			on:input={(e) => formValidator.setField('instance', e.target.value)}
-			class:error={$formState.errors.instance?.length > 0}
-		/>
-		{#if $formState.errors.instance?.length > 0}
-			<span class="error">{$formState.errors.instance[0]}</span>
-		{/if}
-	</div>
-
-	<div class="field">
-		<label for="class">CSS Class</label>
-		<input
-			id="class"
-			type="text"
-			bind:value={$formState.values.class}
-			on:input={(e) =>
-				formValidator.setField('class', FormValidator.sanitizeClassName(e.target.value))}
-			class:error={$formState.errors.class?.length > 0}
-		/>
-		{#if $formState.errors.class?.length > 0}
-			<span class="error">{$formState.errors.class[0]}</span>
-		{/if}
-	</div>
-
-	<button type="submit" disabled={!$formState.isValid || $formState.isSubmitting}>
-		{$formState.isSubmitting ? 'Saving...' : isEditMode ? 'Update' : 'Create'}
-	</button>
-</form>
-
-<style>
-	.field {
-		margin-bottom: 1rem;
-	}
-
-	.error {
-		color: red;
-		font-size: 0.875rem;
-	}
-
-	input.error {
-		border-color: red;
-	}
-</style>
-```
-
-This form validation system provides a robust, type-safe foundation for managing form state in Webflow component applications, ensuring data integrity and providing excellent developer experience.