form0-core 0.3.0 → 0.4.0

package/src/builtins/docs/event/field/setvalue.mdx

@@ -1,239 +0,0 @@
----
-title: "SETVALUE Builtin"
-description: "Set field values in form0 event contexts"
-category: "event"
-tags: ["event", "field", "value", "manipulation"]
----
-
-# SETVALUE Function
-
-The `SETVALUE` builtin sets a field value within event context, automatically collecting the operation for platform execution. This function supports multiple field types including TextField, NumericField, SingleChoiceField, and MultiChoiceField.
-
-## Syntax
-
-```javascript
-SETVALUE('field_dataname', value)
-```
-
-## Parameters
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `fieldDataName` | `string` | The data name of the field to set |
-| `valueToSet` | `any` | The value to set (string, number, array, etc.) |
-
-## Return Value
-
-Returns an operation descriptor for platform execution (for backward compatibility), while internally collecting the operation for automatic execution.
-
-## Examples
-
-### TextField Value
-
-```javascript
-// Set text field value
-SETVALUE('field_dataname', 'value_to_set')
-```
-
-### NumericField Value
-
-```javascript
-// Set numeric field value
-SETVALUE('field_dataname', 12)
-```
-
-### SingleChoiceField Value
-
-```javascript
-// Set single choice field value
-SETVALUE('field_dataname', 'choicefield_value_to_set')
-```
-
-### MultiChoiceField Value
-
-```javascript
-// Set multiple choice field value
-SETVALUE('field_dataname', ['value1', 'value2', 'value3'])
-```
-
-### Conditional Value Setting
-
-```javascript
-// Set field value based on condition
-SETVALUE('discount_field', IF(user.isPremium, 20, 10))
-```
-
-### Dynamic Value Setting
-
-```javascript
-// Set field value based on other fields
-SETVALUE('full_name', firstName + " " + lastName)
-```
-
-## Field Type Compatibility
-
-The `SETVALUE` function supports different value formats for different field types:
-
-| Field Type | Value Format | Example |
-|------------|-------------|---------|
-| `TextField` | String | `'text value'` |
-| `NumericField` | Number | `42` or `3.14` |
-| `SingleChoiceField` | String choice value | `'option1'` |
-| `MultiChoiceField` | Array of strings | `['option1', 'option2']` |
-
-## How It Works
-
-1. **Operation Creation**: Creates a field operation descriptor with type 'FIELD_OPERATION'
-2. **Operation Collection**: Uses `__collectEventOperation` to collect the operation
-3. **Platform Execution**: The platform retrieves and executes collected operations
-4. **Value Formatting**: The platform handles appropriate value formatting for each field type
-5. **Field Update**: The field value is updated in the form state
-
-## Common Use Cases
-
-- **Field auto-population**: Setting field values based on other field changes
-- **Form validation responses**: Setting fields based on validation results
-- **Business rule applications**: Applying complex business logic to field values
-- **User interaction responses**: Updating fields based on user actions
-- **Data calculations**: Setting calculated values in fields
-- **Conditional field updates**: Setting different values based on conditions
-
-## Best Practices
-
-1. **Use correct field data names**: Ensure the field data name exists in your form
-2. **Match field types**: Use appropriate value formats for each field type
-3. **Handle null/undefined**: Consider edge cases in your value assignments
-4. **Event context only**: This function is only available in event contexts
-5. **Platform dependency**: The actual field update depends on platform implementation
-
-## Important Notes
-
-- **Event context only**: This builtin is only available in event contexts, not in calculations
-- **Platform execution**: The actual field value setting is handled by the platform
-- **Operation collection**: Operations are automatically collected and executed
-- **Type handling**: The platform handles value formatting for different field types
-- **Asynchronous execution**: Field updates may occur asynchronously after event completion
-
-## Related Functions
-
-- [`ALERT`](../ui/alert.mdx) - Display alert messages in event contexts
-- [`IF`](../../logical/if.mdx) - Conditional logic for value selection
-- [`AND`](../../logical/and.mdx) - Multiple condition checks
-- [`OR`](../../logical/or.mdx) - Alternative condition checks
-
-## Examples by Use Case
-
-### Auto-calculation Fields
-
-```javascript
-// Calculate and set total price
-SETVALUE('total_price', price * quantity * (1 + taxRate))
-```
-
-### Form Validation Responses
-
-```javascript
-// Set error message field based on validation
-SETVALUE('error_message', 
-  IF(email.isValid, '', 'Please enter a valid email address')
-)
-```
-
-### User Type Based Updates
-
-```javascript
-// Set discount based on user type
-SETVALUE('discount_amount', 
-  IF(user.isPremium, orderTotal * 0.2, orderTotal * 0.05)
-)
-```
-
-### Multi-field Calculations
-
-```javascript
-// Calculate and set BMI
-SETVALUE('bmi', weight / (height * height))
-```
-
-### Choice Field Updates
-
-```javascript
-// Set available options based on category
-SETVALUE('subcategory_options', 
-  IF(category === 'electronics', 
-    ['phone', 'laptop', 'tablet'],
-    ['shirt', 'pants', 'shoes']
-  )
-)
-```
-
-### Data Aggregation
-
-```javascript
-// Set summary field
-SETVALUE('order_summary', 
-  'Items: ' + itemCount + ', Total: $' + totalAmount
-)
-```
-
-## Advanced Examples
-
-### Complex Business Logic
-
-```javascript
-// Calculate shipping cost with multiple factors
-SETVALUE('shipping_cost',
-  IF(country === "US",
-    IF(orderValue > 50, 0, 5.99),
-    IF(orderValue > 100, 10, 15.99)
-  )
-)
-```
-
-### Multi-step Field Updates
-
-```javascript
-// Update multiple related fields
-SETVALUE('first_name', extractedFirstName)
-SETVALUE('last_name', extractedLastName)
-SETVALUE('full_name', extractedFirstName + " " + extractedLastName)
-```
-
-### Conditional Multi-choice Updates
-
-```javascript
-// Set permissions based on user role
-SETVALUE('user_permissions',
-  IF(userRole === 'admin',
-    ['read', 'write', 'delete', 'admin'],
-    IF(userRole === 'editor',
-      ['read', 'write'],
-      ['read']
-    )
-  )
-)
-```
-
-### Dynamic Field Population
-
-```javascript
-// Set field based on external data
-SETVALUE('user_profile', 
-  IF(userId.length > 0, 
-    lookupUserProfile(userId),
-    'No user selected'
-  )
-)
-```
-
-### Form State Management
-
-```javascript
-// Update form status field
-SETVALUE('form_status',
-  IF(allFieldsValid,
-    'ready_for_submission',
-    'incomplete'
-  )
-)
-``` 

package/src/builtins/docs/index.mdx

@@ -1,234 +0,0 @@
----
-title: "form0 Builtins Documentation"
-description: "Complete reference for all form0 builtin functions"
-category: "index"
-tags: ["documentation", "reference", "builtins"]
----
-
-# form0 Builtins Documentation
-
-Welcome to the complete reference for form0 builtin functions. This documentation covers all available functions, their usage, and practical examples.
-
-## Getting Started
-
-- **[Overview](./overview.mdx)** - Introduction to the builtins system
-- **[Quick Reference](#quick-reference)** - Function summary table
-- **[Common Patterns](#common-patterns)** - Frequently used combinations
-
-## Logical Functions
-
-Essential functions for conditional logic and boolean operations:
-
-| Function | Description | Use Cases |
-|----------|-------------|-----------|
-| **[IF](../logical/if.mdx)** | Conditional logic and branching | Field visibility, dynamic values, validation messages |
-| **[AND](../logical/and.mdx)** | Logical AND operations | Multi-condition validation, permission checks |
-| **[OR](../logical/or.mdx)** | Logical OR operations | Alternative requirements, fallback logic |
-
-## Control Functions
-
-Functions for managing calculation flow and results:
-
-| Function | Description | Use Cases |
-|----------|-------------|-----------|
-| **[SETRESULT](../control/setresult.mdx)** | Set calculation results | Price calculations, score computations, field aggregations |
-
-## Quick Reference
-
-### IF Function
-
-```javascript
-IF(condition, trueValue, falseValue)
-```
-
-**Common Usage:**
-- Field visibility: `IF(user.isPremium, true, false)`
-- Dynamic pricing: `IF(quantity > 10, price * 0.9, price)`
-- Validation messages: `IF(age < 18, "Must be 18+", "")`
-
-### AND Function
-
-```javascript
-AND(...conditions)
-```
-
-**Common Usage:**
-- Form validation: `AND(email.isValid, phone.isValid, name.length > 0)`
-- Permission checks: `AND(user.isLoggedIn, user.hasPermission)`
-- Business rules: `AND(inStock, paymentValid, addressComplete)`
-
-### OR Function
-
-```javascript
-OR(...conditions)
-```
-
-**Common Usage:**
-- Alternative requirements: `OR(email.length > 0, phone.length > 0)`
-- Feature detection: `OR(user.isPremium, user.isVip, user.hasSubscription)`
-- Fallback logic: `OR(user.preferredName, user.firstName, "Guest")`
-
-### SETRESULT Function
-
-```javascript
-SETRESULT(value)
-```
-
-**Common Usage:**
-- Price calculations: `SETRESULT(price * quantity * (1 + taxRate))`
-- Score computations: `SETRESULT((score1 + score2 + score3) / 3)`
-- Conditional results: `SETRESULT(IF(eligible, amount, 0))`
-
-## Common Patterns
-
-### Complex Conditional Logic
-
-```javascript
-// Multi-level pricing
-IF(user.type === "premium",
-  IF(order.value > 100, "free-shipping", "discounted-shipping"),
-  IF(order.value > 50, "reduced-shipping", "standard-shipping")
-)
-```
-
-### Validation Chains
-
-```javascript
-// Comprehensive form validation
-AND(
-  email.includes("@"),
-  phone.length >= 10,
-  age >= 18,
-  OR(hasLicense, hasAlternateId),
-  agreedToTerms === true
-)
-```
-
-### Calculation Pipelines
-
-```javascript
-// Complex business calculation
-SETRESULT(
-  (basePrice * quantity) * 
-  IF(user.isPremium, 0.9, 1.0) * 
-  IF(location === "remote", 1.1, 1.0) + 
-  IF(AND(urgent, businessHours), 25, 0)
-)
-```
-
-### Dynamic Field Behavior
-
-```javascript
-// Show field based on multiple conditions
-IF(AND(user.role === "admin", feature.enabled, environment === "production"),
-  "visible",
-  "hidden"
-)
-```
-
-## Function Combinations
-
-### IF + AND
-
-```javascript
-// Show premium features only when all conditions are met
-IF(AND(user.isPremium, feature.enabled, user.region === "US"),
-  premiumContent,
-  standardContent
-)
-```
-
-### IF + OR
-
-```javascript
-// Apply discount if user has any qualifying status
-IF(OR(user.isStudent, user.isSenior, user.isMilitary),
-  discountedPrice,
-  regularPrice
-)
-```
-
-### AND + OR
-
-```javascript
-// Complex eligibility check
-AND(
-  age >= 18,
-  OR(hasDriversLicense, hasStateId, hasPassport),
-  OR(hasProofOfIncome, hasGuarantor)
-)
-```
-
-### Nested Functions
-
-```javascript
-// Sophisticated business logic
-SETRESULT(
-  IF(AND(user.isVip, order.value > 500),
-    IF(OR(user.country === "US", user.country === "CA"),
-      0,  // Free shipping for VIP in North America
-      10  // Reduced shipping for VIP elsewhere
-    ),
-    IF(order.value > 100,
-      5,  // Standard reduced shipping
-      15  // Regular shipping
-    )
-  )
-)
-```
-
-## Best Practices
-
-1. **Keep expressions readable** - Break complex logic into smaller parts
-2. **Use descriptive field names** - Make your conditions self-documenting
-3. **Handle edge cases** - Consider null/undefined values
-4. **Test thoroughly** - Verify all code paths work as expected
-5. **Document complex logic** - Add comments for maintainability
-
-## Performance Tips
-
-- **Order conditions by likelihood** - Put most likely conditions first
-- **Use short-circuit evaluation** - `AND` and `OR` stop early when possible
-- **Avoid deeply nested expressions** - Consider splitting complex logic
-- **Cache expensive operations** - Don't repeat the same calculations
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Undefined values** - Use `OR` for fallbacks: `OR(user.name, "Unknown")`
-2. **Type mismatches** - Ensure consistent data types in comparisons
-3. **Logic errors** - Test all branches of conditional statements
-4. **Performance** - Avoid excessive nesting and complex expressions
-
-### Debugging Tips
-
-- Use simple test cases to verify function behavior
-- Break complex expressions into smaller parts
-- Check that all required fields are available
-- Verify data types match expectations
-
-## Examples by Domain
-
-### E-commerce
-- [Product pricing](../examples/ecommerce.mdx#pricing)
-- [Shipping calculations](../examples/ecommerce.mdx#shipping)
-- [Discount logic](../examples/ecommerce.mdx#discounts)
-
-### User Management
-- [Registration validation](../examples/user-management.mdx#registration)
-- [Permission checks](../examples/user-management.mdx#permissions)
-- [Profile completion](../examples/user-management.mdx#profiles)
-
-### Financial Services
-- [Loan eligibility](../examples/financial.mdx#loans)
-- [Risk assessment](../examples/financial.mdx#risk)
-- [Fee calculations](../examples/financial.mdx#fees)
-
-## Support
-
-For questions or issues:
-- Check the [form0 documentation](https://form0.dev/docs)
-- Review [common patterns](#common-patterns) above
-- See [troubleshooting](#troubleshooting) section
-- Visit the [form0 GitHub repository](https://github.com/form0-dev/form0-core) 

package/src/builtins/docs/logical/and.mdx

@@ -1,141 +0,0 @@
----
-title: "AND Builtin"
-description: "Logical AND operation for form0 expressions"
-category: "logical"
-tags: ["logical", "boolean", "validation"]
----
-
-# AND Function
-
-The `AND` builtin performs logical AND operations, returning `true` only when all provided arguments are truthy.
-
-## Syntax
-
-```javascript
-AND(...args)
-```
-
-## Parameters
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `...args` | `any` | Any number of arguments to evaluate |
-
-## Return Value
-
-Returns `true` if all arguments are truthy, `false` otherwise.
-
-## Examples
-
-### Basic Usage
-
-```javascript
-// Check if user meets multiple criteria
-AND(user.age >= 18, user.hasEmail, user.agreedToTerms)
-```
-
-### Form Validation
-
-```javascript
-// Validate required fields
-AND(name.length > 0, email.includes("@"), phone.length >= 10)
-```
-
-### Complex Conditions
-
-```javascript
-// Check multiple business rules
-AND(
-  order.amount > 0,
-  inventory.stock >= order.quantity,
-  customer.creditScore > 600,
-  customer.accountStatus === "active"
-)
-```
-
-### Field Dependencies
-
-```javascript
-// Show field only when multiple conditions are met
-AND(showAdvanced, user.role === "admin", feature.enabled)
-```
-
-### Nested with Other Functions
-
-```javascript
-// Combine with IF for complex logic
-IF(AND(user.isPremium, order.value > 100), "Free shipping", "Standard shipping")
-```
-
-## Truthiness Rules
-
-The `AND` function uses JavaScript's standard truthiness evaluation:
-
-**Falsy values:**
-- `false`
-- `0`
-- `""` (empty string)
-- `null`
-- `undefined`
-- `NaN`
-
-**Truthy values:**
-- `true`
-- Any non-zero number
-- Any non-empty string
-- Objects and arrays
-- Functions
-
-## Common Use Cases
-
-- **Form validation**: Ensure multiple fields are properly filled
-- **User permissions**: Check if user has multiple required permissions
-- **Business rules**: Validate complex business logic conditions
-- **Feature flags**: Enable features when multiple conditions are met
-- **Data integrity**: Ensure data meets multiple criteria
-
-## Best Practices
-
-1. **Order by likelihood**: Put most likely-to-fail conditions first for better performance
-2. **Use descriptive expressions**: Make conditions self-documenting
-3. **Limit complexity**: Too many conditions can be hard to debug
-4. **Consider short-circuiting**: `AND` stops evaluating once it finds a falsy value
-
-## Performance Notes
-
-- **Short-circuit evaluation**: Stops checking as soon as a falsy value is found
-- **Evaluation order**: Arguments are evaluated left to right
-- **Lazy evaluation**: Later arguments won't be evaluated if earlier ones are falsy
-
-## Related Functions
-
-- [`OR`](./or.mdx) - Logical OR operations
-- [`IF`](./if.mdx) - Conditional logic
-
-## Examples by Use Case
-
-### User Authentication
-
-```javascript
-// Check if user is authenticated and authorized
-AND(user.isLoggedIn, user.permissions.includes("read"), user.sessionValid)
-```
-
-### E-commerce Validation
-
-```javascript
-// Validate order can be processed
-AND(
-  product.inStock,
-  customer.paymentMethodValid,
-  shippingAddress.isComplete,
-  order.total > 0
-)
-```
-
-### Feature Gating
-
-```javascript
-// Enable beta feature
-AND(user.betaOptIn, feature.betaEnabled, environment === "production")
-``` 

package/src/builtins/docs/logical/if.mdx

@@ -1,94 +0,0 @@
----
-title: "IF Builtin"
-description: "Conditional logic function for form0 expressions"
-category: "logical"
-tags: ["conditional", "logic", "branching"]
----
-
-# IF Function
-
-The `IF` builtin provides conditional logic within form0 expressions, allowing you to return different values based on a condition.
-
-## Syntax
-
-```javascript
-IF(condition, trueValue, falseValue)
-```
-
-## Parameters
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `condition` | `boolean` | The condition to evaluate |
-| `trueValue` | `any` | Value returned when condition is true |
-| `falseValue` | `any` | Value returned when condition is false |
-
-## Return Value
-
-Returns `trueValue` if the condition is truthy, otherwise returns `falseValue`.
-
-## Examples
-
-### Basic Usage
-
-```javascript
-// Show discount message based on user status
-IF(user.isPremium, "20% off", "No discount")
-```
-
-### Numeric Calculations
-
-```javascript
-// Apply different tax rates
-IF(country === "US", price * 0.08, price * 0.20)
-```
-
-### Nested Conditions
-
-```javascript
-// Determine shipping cost based on location and order value
-IF(country === "US", 
-  IF(orderValue > 50, 0, 5.99), 
-  IF(orderValue > 100, 10, 15.99)
-)
-```
-
-### Field Visibility
-
-```javascript
-// Show additional fields for premium users
-IF(user.type === "premium", true, false)
-```
-
-### Dynamic Form Validation
-
-```javascript
-// Conditional validation messages
-IF(age < 18, "Must be 18 or older", "")
-```
-
-## Common Use Cases
-
-- **Conditional pricing**: Different prices based on user type or location
-- **Dynamic field visibility**: Show/hide fields based on other field values
-- **Validation messages**: Display different error messages based on conditions
-- **User experience**: Personalize content based on user preferences
-- **Business logic**: Implement complex conditional rules
-
-## Best Practices
-
-1. **Keep conditions simple**: Complex conditions can be hard to read and debug
-2. **Use descriptive variable names**: Make your conditions self-documenting
-3. **Consider nested IFs carefully**: Too many levels can become difficult to maintain
-4. **Test edge cases**: Ensure your conditions handle all possible scenarios
-
-## Related Functions
-
-- [`AND`](./and.mdx) - Logical AND operations
-- [`OR`](./or.mdx) - Logical OR operations
-
-## Notes
-
-- The condition is evaluated using JavaScript's truthiness rules
-- Both `trueValue` and `falseValue` can be of any type
-- The function is lazy-evaluated - only the returned branch is computed