pict-section-formeditor 1.0.0

package/user-documentation/solverfunctions/runsolvers.md

@@ -0,0 +1,49 @@
+# runsolvers
+
+Triggers a re-execution of all solver expressions across all form views.
+
+## Syntax
+
+```
+runsolvers()
+```
+
+## Parameters
+
+This function takes no parameters.
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `runsolvers` function triggers a complete re-execution of all active solver expressions across all form views. This forces a full recalculation pass, which can be necessary after programmatic changes to form state that would not otherwise trigger solver execution. Use this function with caution, as calling it from within a solver can create infinite loops if not properly controlled with ordinal gating.
+
+## Examples
+
+### Triggering a solver re-run
+
+```expression
+runsolvers()
+// Triggers re-execution of all active solver expressions
+```
+
+## Use Cases
+
+- **Forcing recalculation**: Trigger a full solver pass after programmatically modifying application state
+- **Synchronization**: Ensure all calculated values are up to date after bulk data changes
+- **Chain reactions**: Propagate changes that require multiple solver passes to fully resolve
+
+## Related Functions
+
+- [setsolverordinalenabled](./setsolverordinalenabled.md) - Enables or disables solvers with a specific ordinal
+- [enablesolverordinal](./enablesolverordinal.md) - Enables all solvers with the specified ordinal
+- [disablesolverordinal](./disablesolverordinal.md) - Disables all solvers with the specified ordinal
+
+## Notes
+
+- Use with caution: calling `runsolvers()` from within a solver expression can create infinite loops
+- Protect against infinite loops by using ordinal gating (disable the calling ordinal before invoking `runsolvers`)
+- All active (enabled) solver ordinals will execute in order
+- Disabled ordinals are skipped during the re-execution

package/user-documentation/solverfunctions/setconcatenate.md

@@ -0,0 +1,64 @@
+# setconcatenate
+
+Concatenates two arrays into one.
+
+## Syntax
+
+```
+setconcatenate(array1, array2)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array1` | Array | First array |
+| `array2` | Array | Second array |
+
+## Returns
+
+Array - Combined array with elements from both inputs.
+
+## Description
+
+The `setconcatenate` function combines two arrays into a single array by appending the second array to the first.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = SETCONCATENATE([1, 2, 3], [4, 5, 6])
+// Result: [1, 2, 3, 4, 5, 6]
+```
+
+### Combining Data
+
+```expression
+AllItems = SETCONCATENATE(Category1Items, Category2Items)
+```
+
+### Multiple Concatenations
+
+```expression
+Combined = SETCONCATENATE(SETCONCATENATE(Set1, Set2), Set3)
+```
+
+## Use Cases
+
+- **Data merging**: Combine datasets
+- **Aggregation**: Collect from multiple sources
+- **Array building**: Build arrays incrementally
+- **Set union**: Combine sets (may have duplicates)
+
+## Related Functions
+
+- [arrayconcat](./arrayconcat.md) - Alternative concatenation
+- [flatten](./flatten.md) - Flatten nested arrays
+- [countset](./countset.md) - Count combined elements
+
+## Notes
+
+- Does not remove duplicates
+- Order is preserved (array1 then array2)
+- Uses the Math service's `setConcatenate` method

package/user-documentation/solverfunctions/setgroupvisibility.md

@@ -0,0 +1,60 @@
+# setgroupvisibility
+
+Sets a specific group's visibility within a section.
+
+## Syntax
+
+```
+setgroupvisibility(sectionHash, groupHash, visible)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sectionHash` | String | The hash identifier of the section containing the group |
+| `groupHash` | String | The hash identifier of the group |
+| `visible` | Boolean | `true` to show the group, `false` to hide it |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `setgroupvisibility` function controls the visibility of a specific group within a form section. Groups are subdivisions within sections that contain one or more form inputs. This function allows fine-grained control over which groups of inputs are visible, enabling more detailed conditional display logic than section-level visibility alone.
+
+## Examples
+
+### Toggling a group based on a condition
+
+```expression
+setgroupvisibility("S1", "S1_G2", ShowDetails)
+// If ShowDetails is true, group S1_G2 within section S1 is shown
+// If ShowDetails is false, group S1_G2 within section S1 is hidden
+```
+
+### Hiding a group
+
+```expression
+setgroupvisibility("ContactInfo", "AlternateAddress", false)
+// Hides the AlternateAddress group within the ContactInfo section
+```
+
+## Use Cases
+
+- **Fine-grained visibility**: Show or hide individual groups of inputs within a section
+- **Conditional fields**: Display additional input groups based on user selections
+- **Progressive disclosure**: Reveal groups of related fields as the user provides information
+
+## Related Functions
+
+- [setsectionvisibility](./setsectionvisibility.md) - Sets a specific section's visibility
+- [showsections](./showsections.md) - Makes the specified form sections visible
+- [hidesections](./hidesections.md) - Hides the specified form sections
+
+## Notes
+
+- Both the section hash and group hash must match hashes defined in the form configuration
+- The group retains its data in the application state regardless of visibility
+- The parent section must be visible for group visibility changes to have a visual effect

package/user-documentation/solverfunctions/setsectionvisibility.md

@@ -0,0 +1,59 @@
+# setsectionvisibility
+
+Sets a specific section's visibility.
+
+## Syntax
+
+```
+setsectionvisibility(sectionHash, visible)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sectionHash` | String | The hash identifier of the section |
+| `visible` | Boolean or String | `true`/`false` or `"1"`/`"0"` to set visibility |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `setsectionvisibility` function sets the visibility of a single form section based on a boolean or string value. Unlike `showsections` and `hidesections` which operate on lists, this function targets one section and accepts a dynamic visibility value. This makes it ideal for binding section visibility directly to a calculated or user-driven boolean expression.
+
+## Examples
+
+### Toggling visibility based on a flag
+
+```expression
+setsectionvisibility("AdvancedOptions", ShowAdvanced)
+// If ShowAdvanced is true, the AdvancedOptions section is shown
+// If ShowAdvanced is false, the AdvancedOptions section is hidden
+```
+
+### Using a string value
+
+```expression
+setsectionvisibility("ExtraFields", "1")
+// Shows the ExtraFields section
+```
+
+## Use Cases
+
+- **Dynamic visibility**: Bind a section's visibility to a checkbox or toggle input
+- **Calculated visibility**: Show or hide a section based on the result of a solver expression
+- **Conditional display**: Control section visibility using any boolean-producing expression
+
+## Related Functions
+
+- [showsections](./showsections.md) - Makes the specified form sections visible
+- [hidesections](./hidesections.md) - Hides the specified form sections
+- [setgroupvisibility](./setgroupvisibility.md) - Sets a specific group's visibility within a section
+
+## Notes
+
+- The `visible` parameter accepts boolean values (`true`/`false`) or string equivalents (`"1"`/`"0"`)
+- The section hash must match a hash defined in the form configuration
+- The section retains its data in the application state regardless of visibility

package/user-documentation/solverfunctions/setsolverordinalenabled.md

@@ -0,0 +1,59 @@
+# setsolverordinalenabled
+
+Enables or disables all solvers with the specified ordinal number.
+
+## Syntax
+
+```
+setsolverordinalenabled(ordinal, enabled)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `ordinal` | Integer | The ordinal number of the solver group to enable or disable |
+| `enabled` | Boolean | `true` to enable the solvers, `false` to disable them |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `setsolverordinalenabled` function controls whether all solvers assigned to a specific ordinal number are executed during solver runs. Solvers are organized by ordinal numbers that determine their execution order. By disabling an ordinal, all solvers at that ordinal are skipped during execution. This enables conditional execution of entire groups of solver expressions based on form state, user input, or other conditions.
+
+## Examples
+
+### Toggling solvers based on a mode flag
+
+```expression
+setsolverordinalenabled(2, IsAdvancedMode)
+// If IsAdvancedMode is true, ordinal 2 solvers run; otherwise they are skipped
+```
+
+### Disabling a solver group
+
+```expression
+setsolverordinalenabled(5, false)
+// Disables all solvers with ordinal 5
+```
+
+## Use Cases
+
+- **Conditional solver execution**: Enable or disable groups of solvers based on form state
+- **Performance optimization**: Skip unnecessary solver calculations when they are not relevant
+- **Mode switching**: Enable different sets of solvers for different form modes (e.g., basic vs. advanced)
+
+## Related Functions
+
+- [enablesolverordinal](./enablesolverordinal.md) - Enables all solvers with the specified ordinal
+- [disablesolverordinal](./disablesolverordinal.md) - Disables all solvers with the specified ordinal
+- [runsolvers](./runsolvers.md) - Triggers re-execution of all solver expressions
+
+## Notes
+
+- Disabled ordinals skip execution entirely during solver runs
+- Used for conditional execution of entire groups of solvers
+- The ordinal number must correspond to an ordinal defined in the solver configuration
+- Changes take effect on the next solver run

package/user-documentation/solverfunctions/settabularrowlength.md

@@ -0,0 +1,57 @@
+# settabularrowlength
+
+Sets the number of rows in a tabular data group.
+
+## Syntax
+
+```
+settabularrowlength(sectionHash, groupHash, length)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sectionHash` | String | The hash identifier of the section containing the tabular group |
+| `groupHash` | String | The hash identifier of the tabular group |
+| `length` | Integer | The desired number of rows |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `settabularrowlength` function sets the number of rows in a tabular data group to the specified length. If the current number of rows is less than the specified length, new rows are added. If the current number is greater, excess rows may be removed depending on the optional fourth parameter. This function is useful for programmatically controlling the size of tabular data sections based on external data or user input.
+
+## Examples
+
+### Setting a table to 10 rows
+
+```expression
+settabularrowlength("DataSection", "DataGroup", 10)
+// Sets the DataGroup table in DataSection to have exactly 10 rows
+```
+
+### Setting row count with deletion of extra rows
+
+```expression
+settabularrowlength("Orders", "LineItems", RequiredRows, true)
+// Sets the row count and deletes any extra rows beyond RequiredRows
+```
+
+## Use Cases
+
+- **Data loading**: Set the correct number of rows when loading external data into a tabular group
+- **Dynamic row management**: Adjust the number of rows based on a calculated value or user selection
+- **Initialization**: Pre-populate a tabular section with a specific number of empty rows
+
+## Related Functions
+
+- [refreshtabularsection](./refreshtabularsection.md) - Forces a tabular section to re-render its display
+
+## Notes
+
+- Optional fourth parameter is a boolean that controls whether extra rows are deleted when reducing the row count
+- The section and group hashes must match hashes defined in the form configuration
+- Adding rows creates empty rows with default values

package/user-documentation/solverfunctions/setvalue.md

@@ -0,0 +1,65 @@
+# setvalue
+
+Sets a value in the application state at the specified path.
+
+## Syntax
+
+```
+setvalue(address, value)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `address` | String | Dot-notation path to the state location (must be quoted) |
+| `value` | Any | The value to set at the specified path |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `setvalue` function writes a value into the application state at the location specified by the address parameter. The address uses dot-notation to identify the path within the state object. This function is essential for solver expressions that need to store calculated results, update form fields, or modify application state based on computed values. The address parameter must be a quoted string.
+
+## Examples
+
+### Setting a calculated total
+
+```expression
+setvalue("AppData.TotalPrice", Price * Quantity)
+// Sets the TotalPrice field in AppData to the product of Price and Quantity
+```
+
+### Setting a status flag
+
+```expression
+setvalue("FormState.IsComplete", true)
+// Sets the IsComplete flag to true
+```
+
+### Setting a nested value
+
+```expression
+setvalue("Order.Summary.GrandTotal", Subtotal + Tax + Shipping)
+// Sets a deeply nested value in the application state
+```
+
+## Use Cases
+
+- **Storing calculations**: Write the results of solver calculations back into the application state
+- **Updating form fields**: Programmatically set the value of form inputs
+- **Managing state flags**: Set boolean flags or status values based on form conditions
+- **Cross-section data sharing**: Write values that can be read by other sections or solvers
+
+## Related Functions
+
+- [logvalues](./logvalues.md) - Logs values to the browser console for debugging
+
+## Notes
+
+- The address must be a quoted string using dot-notation (e.g., `"AppData.Field"`)
+- The value can be any type: string, number, boolean, array, or object
+- Setting a value does not automatically trigger a solver re-run
+- The path will be created if it does not already exist in the state

package/user-documentation/solverfunctions/showsections.md

@@ -0,0 +1,58 @@
+# showsections
+
+Makes the specified form sections visible.
+
+## Syntax
+
+```
+showsections(sectionHashes)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sectionHashes` | Array or String | An array of section hash strings, or a single section hash string |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `showsections` function makes one or more form sections visible on the page. You can pass either an array of section hash strings to show multiple sections at once, or a single string to show one section. This is commonly used in conjunction with solver logic to conditionally display parts of a form based on user input or other state.
+
+## Examples
+
+### Showing multiple sections from an array
+
+```expression
+showsections(VisibleSectionList)
+// Where VisibleSectionList is an array like ["S1", "S3"]
+// Makes sections S1 and S3 visible
+```
+
+### Showing a single section
+
+```expression
+showsections("AdvancedOptions")
+// Makes the AdvancedOptions section visible
+```
+
+## Use Cases
+
+- **Conditional form display**: Show sections of a form based on user selections or calculated state
+- **Progressive disclosure**: Reveal additional form sections as the user completes earlier sections
+- **Role-based visibility**: Show different sections depending on user role or permissions
+
+## Related Functions
+
+- [hidesections](./hidesections.md) - Hides the specified form sections
+- [setsectionvisibility](./setsectionvisibility.md) - Sets a specific section's visibility with a boolean
+- [setgroupvisibility](./setgroupvisibility.md) - Sets a specific group's visibility within a section
+
+## Notes
+
+- Accepts either an array of section hash strings or a single string
+- Section hashes must match the hashes defined in the form configuration
+- Does not affect the visibility of groups within the sections

package/user-documentation/solverfunctions/sin.md

@@ -0,0 +1,83 @@
+# sin
+
+Calculates the sine of an angle (in radians).
+
+## Syntax
+
+```
+sin(radians)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `radians` | Number/String | The angle in radians |
+
+## Returns
+
+String - The sine of the angle.
+
+## Description
+
+The `sin` function calculates the sine of an angle. The input must be in radians. Use the `rad()` function to convert degrees to radians if needed.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = sin(0)
+// Result: "0"
+
+Result = sin(1.5707963267948966)  // π/2
+// Result: "1" (approximately)
+```
+
+### Converting from Degrees
+
+```expression
+// Sine of 60 degrees
+Result = sin(rad(60))
+// Result: "0.8660254037844386"
+
+// Sine of 90 degrees
+Result = sin(rad(90))
+// Result: "1"
+```
+
+### In Complex Expressions
+
+```expression
+// From unit tests
+Result = sqrt(100 * (C + 30)) + sin(Depth - Width) / 10
+// With C=-13, Depth=100.203, Width=10.5
+// Result: "41.32965489638783839821"
+```
+
+### Waveform Calculations
+
+```expression
+// Simple harmonic motion
+Position = Amplitude * sin(Frequency * Time + Phase)
+```
+
+## Use Cases
+
+- **Trigonometry**: Triangle calculations
+- **Physics**: Wave motion, oscillations, projectile motion
+- **Graphics**: Rotation, animation
+- **Engineering**: Signal processing, vibration analysis
+
+## Related Functions
+
+- [cos](./cos.md) - Cosine
+- [tan](./tan.md) - Tangent
+- [rad](./rad.md) - Convert degrees to radians
+- [pi](./pi.md) - Pi constant
+
+## Notes
+
+- Input must be in radians, not degrees
+- Use `rad(degrees)` to convert from degrees
+- Uses JavaScript's `Math.sin()` internally

package/user-documentation/solverfunctions/slice.md

@@ -0,0 +1,80 @@
+# slice
+
+Extracts a portion of an array.
+
+## Syntax
+
+```
+slice(array, start)
+slice(array, start, end)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | The array to slice |
+| `start` | Number | Starting index (0-based) |
+| `end` | Number | Ending index (optional, exclusive) |
+
+## Returns
+
+Array - A new array containing the extracted elements.
+
+## Description
+
+The `slice` function extracts a section of an array and returns it as a new array. The original array is not modified.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = SLICE([1, 2, 3, 4, 5], 1, 4)
+// Result: [2, 3, 4]
+```
+
+### From Start Index to End
+
+```expression
+// Get everything from index 2 onwards
+Result = SLICE([1, 2, 3, 4, 5], 2)
+// Result: [3, 4, 5]
+```
+
+### First N Elements
+
+```expression
+// Get first 3 elements
+TopThree = SLICE(SortedScores, 0, 3)
+```
+
+### Pagination
+
+```expression
+// Get page of results
+PageSize = 10
+PageStart = (PageNumber - 1) * PageSize
+PageData = SLICE(AllData, PageStart, PageStart + PageSize)
+```
+
+## Use Cases
+
+- **Pagination**: Extract page of results
+- **Top N**: Get first N elements
+- **Data sampling**: Extract subset of data
+- **Range selection**: Select specific range
+
+## Related Functions
+
+- [sortset](./sortset.md) - Sort before slicing
+- [flatten](./flatten.md) - Flatten before slicing
+- [count](./count.md) - Get array length
+
+## Notes
+
+- Start index is 0-based
+- End index is exclusive
+- Negative indices may not be supported
+- Does not modify original array
+- Uses JavaScript array slice behavior

package/user-documentation/solverfunctions/smallestinset.md

@@ -0,0 +1,63 @@
+# smallestinset
+
+Returns the smallest value from a set/array.
+
+## Syntax
+
+```
+smallestinset(set)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `set` | Array | The array of values |
+
+## Returns
+
+String - The smallest value in the set.
+
+## Description
+
+The `smallestinset` function finds and returns the smallest (minimum) value from an array. This is an alternative to the `min` function specifically designed for set operations.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = SMALLESTINSET([5, 2, 8, 1, 9])
+// Result: "1"
+```
+
+### With Data
+
+```expression
+LowestPrice = SMALLESTINSET(FLATTEN(AppData.Products.price))
+```
+
+### Temperature Data
+
+```expression
+MinTemp = SMALLESTINSET(DailyTemperatures)
+```
+
+## Use Cases
+
+- **Analysis**: Find minimum values
+- **Thresholds**: Determine lower bounds
+- **Comparisons**: Find lowest in category
+- **Validation**: Check minimum constraints
+
+## Related Functions
+
+- [largestinset](./largestinset.md) - Find maximum value
+- [min](./min.md) - Alternative minimum function
+- [sortset](./sortset.md) - Sort to find extremes
+
+## Notes
+
+- Returns result as string
+- Works with numeric values
+- Uses the Math service's `smallestInSet` method