pict-section-formeditor 1.0.0

package/user-documentation/solverfunctions/colorgroupbackground.md

@@ -0,0 +1,60 @@
+# colorgroupbackground
+
+Sets the background color of a form group.
+
+## Syntax
+
+```
+colorgroupbackground(sectionHash, groupHash, color)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sectionHash` | String | The hash identifier of the section containing the group |
+| `groupHash` | String | The hash identifier of the group |
+| `color` | String | HTML hex color string (e.g., `"#E0FFE0"`) |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `colorgroupbackground` function sets the background color of a specific group within a form section. This provides more granular visual control than section-level coloring, allowing individual groups of inputs to be highlighted independently. It is useful for drawing attention to specific parts of a form or providing visual feedback at the group level.
+
+## Examples
+
+### Highlighting a group with a light green background
+
+```expression
+colorgroupbackground("S1", "S1_G1", "#E0FFE0")
+// Sets the background of group S1_G1 in section S1 to light green
+```
+
+### Conditional group coloring
+
+```expression
+GroupColor = IF(GroupIsComplete, "#E0FFE0", "#FFFFFF")
+colorgroupbackground("Details", "RequiredFields", GroupColor)
+// Green background when all required fields are filled, white otherwise
+```
+
+## Use Cases
+
+- **Group-level validation**: Color a group based on whether its inputs pass validation
+- **Visual grouping**: Use color to distinguish between different groups within a section
+- **Completion tracking**: Indicate which groups of fields have been completed
+
+## Related Functions
+
+- [generatehtmlhexcolor](./generatehtmlhexcolor.md) - Generates an HTML hex color string from RGB components
+- [colorsectionbackground](./colorsectionbackground.md) - Sets the background color of a form section
+- [colorinputbackground](./colorinputbackground.md) - Sets the background color of a form input
+
+## Notes
+
+- The color parameter should be a valid HTML hex color string including the `#` prefix
+- Both the section hash and group hash must match hashes defined in the form configuration
+- The parent section must be visible for the group color change to be seen

package/user-documentation/solverfunctions/colorinputbackground.md

@@ -0,0 +1,62 @@
+# colorinputbackground
+
+Sets the background color of a form input.
+
+## Syntax
+
+```
+colorinputbackground(sectionHash, inputHash, color)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sectionHash` | String | The hash identifier of the section containing the input |
+| `inputHash` | String | The hash identifier of the input |
+| `color` | String | HTML hex color string (e.g., `"#FFFFCC"`) |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `colorinputbackground` function sets the background color of a specific form input element. This is the most granular color control available, targeting individual inputs within a form. It is useful for field-level validation feedback, highlighting specific fields that need attention, or providing visual cues based on calculated values. The function also accepts an optional fourth parameter to control apply change behavior and an optional fifth parameter for a CSS selector.
+
+## Examples
+
+### Highlighting a price field
+
+```expression
+colorinputbackground("S1", "Price", "#FFFFCC")
+// Sets the background of the Price input in section S1 to light yellow
+```
+
+### Validation coloring
+
+```expression
+FieldColor = IF(Price > 0, "#FFFFFF", "#FFE0E0")
+colorinputbackground("OrderDetails", "Price", FieldColor)
+// White background if Price is valid, light red if not
+```
+
+## Use Cases
+
+- **Field-level validation**: Highlight individual fields that have validation errors
+- **Required field indication**: Color required fields to draw user attention
+- **Value-based formatting**: Change input color based on its value (e.g., negative numbers in red)
+
+## Related Functions
+
+- [generatehtmlhexcolor](./generatehtmlhexcolor.md) - Generates an HTML hex color string from RGB components
+- [colorsectionbackground](./colorsectionbackground.md) - Sets the background color of a form section
+- [colorgroupbackground](./colorgroupbackground.md) - Sets the background color of a form group
+- [colorinputbackgroundtabular](./colorinputbackgroundtabular.md) - Sets the background color of a cell in a tabular group
+
+## Notes
+
+- The color parameter should be a valid HTML hex color string including the `#` prefix
+- Optional fourth parameter controls apply change behavior
+- Optional fifth parameter specifies a CSS selector for targeting specific sub-elements
+- The section and input hashes must match hashes defined in the form configuration

package/user-documentation/solverfunctions/colorinputbackgroundtabular.md

@@ -0,0 +1,64 @@
+# colorinputbackgroundtabular
+
+Sets the background color of a specific cell in a tabular group.
+
+## Syntax
+
+```
+colorinputbackgroundtabular(sectionHash, groupHash, inputHash, rowIndex, color)
+```
+
+## 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 |
+| `inputHash` | String | The hash identifier of the input (column) |
+| `rowIndex` | Integer | The zero-based row index |
+| `color` | String | HTML hex color string (e.g., `"#FFFFCC"`) |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `colorinputbackgroundtabular` function sets the background color of a specific cell within a tabular form group. It targets a single cell by its section, group, input (column), and row index. This enables cell-level visual formatting in tabular data, such as highlighting specific values, indicating validation errors in individual cells, or applying conditional formatting across a data grid. The function also accepts optional parameters for apply change behavior, CSS selector, and element ID prefix.
+
+## Examples
+
+### Highlighting a cell in the first row
+
+```expression
+colorinputbackgroundtabular("S1", "S1_G1", "Price", 0, "#FFFFCC")
+// Sets the background of the Price cell in row 0 of group S1_G1 to light yellow
+```
+
+### Conditional cell coloring
+
+```expression
+CellColor = IF(RowTotal > Budget, "#FFE0E0", "#FFFFFF")
+colorinputbackgroundtabular("DataSection", "DataGroup", "Total", RowIdx, CellColor)
+// Red background if the row total exceeds budget, white otherwise
+```
+
+## Use Cases
+
+- **Cell-level validation**: Highlight specific cells that contain invalid or out-of-range values
+- **Conditional formatting**: Apply spreadsheet-like conditional formatting to tabular data
+- **Data visualization**: Use color to represent data values in a tabular layout
+
+## Related Functions
+
+- [generatehtmlhexcolor](./generatehtmlhexcolor.md) - Generates an HTML hex color string from RGB components
+- [colorinputbackground](./colorinputbackground.md) - Sets the background color of a non-tabular form input
+- [colorgroupbackground](./colorgroupbackground.md) - Sets the background color of a form group
+
+## Notes
+
+- The `rowIndex` parameter is zero-based (first row is 0)
+- Optional sixth parameter controls apply change behavior
+- Optional seventh parameter specifies a CSS selector for targeting specific sub-elements
+- Optional eighth parameter specifies an element ID prefix
+- All hash parameters must match hashes defined in the form configuration

package/user-documentation/solverfunctions/colorsectionbackground.md

@@ -0,0 +1,59 @@
+# colorsectionbackground
+
+Sets the background color of a form section.
+
+## Syntax
+
+```
+colorsectionbackground(sectionHash, color)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sectionHash` | String | The hash identifier of the section |
+| `color` | String | HTML hex color string (e.g., `"#FFE0E0"`) |
+
+## Returns
+
+Void. This function does not return a value.
+
+## Description
+
+The `colorsectionbackground` function sets the background color of a form section to the specified HTML hex color. This is useful for visually highlighting sections based on form state, validation results, or other conditions. The function can also accept an optional third parameter to control apply change behavior.
+
+## Examples
+
+### Highlighting a section with a light red background
+
+```expression
+colorsectionbackground("S1", "#FFE0E0")
+// Sets the background of section S1 to light red
+```
+
+### Dynamic coloring based on status
+
+```expression
+SectionColor = IF(IsValid, "#E0FFE0", "#FFE0E0")
+colorsectionbackground("FormData", SectionColor)
+// Green background if valid, red background if not
+```
+
+## Use Cases
+
+- **Validation feedback**: Color a section red when it contains validation errors, green when valid
+- **Status indication**: Visually indicate the state of a section based on its completion or status
+- **Attention drawing**: Highlight a section that requires user attention
+
+## Related Functions
+
+- [generatehtmlhexcolor](./generatehtmlhexcolor.md) - Generates an HTML hex color string from RGB components
+- [colorgroupbackground](./colorgroupbackground.md) - Sets the background color of a form group
+- [colorinputbackground](./colorinputbackground.md) - Sets the background color of a form input
+
+## Notes
+
+- The color parameter should be a valid HTML hex color string including the `#` prefix
+- Can accept an optional third parameter for apply change behavior
+- The section hash must match a hash defined in the form configuration

package/user-documentation/solverfunctions/compare.md

@@ -0,0 +1,72 @@
+# compare
+
+Compares two values and returns their relationship.
+
+## Syntax
+
+```
+compare(value1, value2)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value1` | Number | First value to compare |
+| `value2` | Number | Second value to compare |
+
+## Returns
+
+String - Returns "-1" if value1 < value2, "0" if equal, "1" if value1 > value2.
+
+## Description
+
+The `compare` function compares two numeric values and returns a value indicating their relative order. This is useful for sorting and conditional logic.
+
+## Examples
+
+### Basic Comparisons
+
+```expression
+Result = COMPARE(5, 10)
+// Result: "-1" (5 is less than 10)
+
+Result = COMPARE(10, 5)
+// Result: "1" (10 is greater than 5)
+
+Result = COMPARE(5, 5)
+// Result: "0" (equal)
+```
+
+### With Variables
+
+```expression
+Comparison = COMPARE(ActualValue, ExpectedValue)
+```
+
+### Conditional Logic
+
+```expression
+// Check if over budget
+OverBudget = COMPARE(Spending, Budget) == 1
+```
+
+## Use Cases
+
+- **Sorting**: Determine sort order
+- **Validation**: Check thresholds
+- **Business logic**: Compare metrics
+- **Conditional processing**: Branch based on comparison
+
+## Related Functions
+
+- [max](./max.md) - Find maximum value
+- [min](./min.md) - Find minimum value
+- [if](./if.md) - Conditional logic
+- [when](./when.md) - Conditional expression
+
+## Notes
+
+- Returns string: "-1", "0", or "1"
+- Uses the Math service's `comparePrecise` method
+- Works with arbitrary precision numbers

package/user-documentation/solverfunctions/concat.md

@@ -0,0 +1,73 @@
+# concat
+
+Concatenates values into a single string with space separation.
+
+## Syntax
+
+```
+concat(value1, value2, ...)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `values` | Any | Values to concatenate |
+
+## Returns
+
+String - All values joined with spaces.
+
+## Description
+
+The `concat` function joins multiple values into a single string, automatically adding spaces between each value. This is useful for building display strings and messages.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = CONCAT("Hello", "World")
+// Result: "Hello World"
+```
+
+### Multiple Values
+
+```expression
+FullName = CONCAT(FirstName, MiddleName, LastName)
+// Result: "John William Smith"
+```
+
+### With Numbers
+
+```expression
+Message = CONCAT("Total:", 42, "items")
+// Result: "Total: 42 items"
+```
+
+### Building Labels
+
+```expression
+Label = CONCAT(ProductName, "-", Size, Color)
+// Result: "Widget - Large Blue"
+```
+
+## Use Cases
+
+- **Display strings**: Build user-facing text
+- **Labels**: Create composite labels
+- **Messages**: Construct messages from parts
+- **Reports**: Combine data for display
+
+## Related Functions
+
+- [concatraw](./concatraw.md) - Concatenate without spaces
+- [join](./join.md) - Join with custom separator
+- [joinraw](./joinraw.md) - Join without spaces
+
+## Notes
+
+- Automatically adds spaces between values
+- Converts non-string values to strings
+- Use `concatraw` for no separator
+- Uses the DataFormat service internally

package/user-documentation/solverfunctions/concatraw.md

@@ -0,0 +1,73 @@
+# concatraw
+
+Concatenates values into a single string without any separation.
+
+## Syntax
+
+```
+concatraw(value1, value2, ...)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `values` | Any | Values to concatenate |
+
+## Returns
+
+String - All values joined with no separator.
+
+## Description
+
+The `concatraw` function joins multiple values into a single string without adding any spaces or separators between them. This is useful for building identifiers, codes, and other concatenated strings where spaces would be inappropriate.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = CONCATRAW("Hello", "World")
+// Result: "HelloWorld"
+```
+
+### Building Codes
+
+```expression
+ProductCode = CONCATRAW(Category, "-", ItemNumber)
+// Result: "ELEC-12345"
+```
+
+### File Names
+
+```expression
+FileName = CONCATRAW(BaseName, "_", Version, ".txt")
+// Result: "report_v2.txt"
+```
+
+### Identifiers
+
+```expression
+UniqueID = CONCATRAW(Prefix, ID, Suffix)
+// Result: "USR00123ACT"
+```
+
+## Use Cases
+
+- **Identifiers**: Build unique IDs
+- **File names**: Construct file names
+- **Codes**: Create product/reference codes
+- **URLs**: Build URL components
+
+## Related Functions
+
+- [concat](./concat.md) - Concatenate with spaces
+- [join](./join.md) - Join with custom separator
+- [joinraw](./joinraw.md) - Join array without spaces
+
+## Notes
+
+- No separator between values
+- Converts non-string values to strings
+- Useful when spaces are not wanted
+- Uses the DataFormat service internally

package/user-documentation/solverfunctions/cos.md

@@ -0,0 +1,75 @@
+# cos
+
+Calculates the cosine of an angle (in radians).
+
+## Syntax
+
+```
+cos(radians)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `radians` | Number/String | The angle in radians |
+
+## Returns
+
+String - The cosine of the angle.
+
+## Description
+
+The `cos` function calculates the cosine 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 = cos(0)
+// Result: "1"
+
+Result = cos(3.14159265358979)  // π
+// Result: "-1" (approximately)
+```
+
+### Converting from Degrees
+
+```expression
+// Cosine of 60 degrees
+Result = cos(rad(60))
+// Result: "0.5"
+
+// Cosine of 90 degrees
+Result = cos(rad(90))
+// Result: "0" (approximately)
+```
+
+### In Expressions
+
+```expression
+// Circle point calculations
+X = Radius * cos(Angle)
+Y = Radius * sin(Angle)
+```
+
+## Use Cases
+
+- **Trigonometry**: Triangle calculations, angle computations
+- **Graphics**: Rotation matrices, 3D transformations
+- **Physics**: Projectile motion (horizontal component)
+- **Engineering**: Phase calculations in AC circuits
+
+## Related Functions
+
+- [sin](./sin.md) - Sine
+- [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.cos()` internally

package/user-documentation/solverfunctions/count.md

@@ -0,0 +1,73 @@
+# count
+
+Returns the count of elements in an array or set.
+
+## Syntax
+
+```
+count(array)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | The array to count elements from |
+
+## Returns
+
+String - The number of elements in the array.
+
+## Description
+
+The `count` function returns the number of elements in an array. This is useful for determining the size of datasets or validating data.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = COUNT([1, 2, 3, 4, 5])
+// Result: "5"
+```
+
+### With Data Path
+
+```expression
+// Count records in a dataset
+TotalCities = COUNT(AppData.Cities)
+```
+
+### Conditional Counting
+
+```expression
+// Use with filtered data
+ActiveUsers = COUNT(FLATTEN(AppData.Users.active))
+```
+
+### Validation
+
+```expression
+// Verify expected count
+IsValid = COUNT(Records) == ExpectedCount
+```
+
+## Use Cases
+
+- **Data validation**: Verify record counts
+- **Statistics**: Determine sample size
+- **Pagination**: Calculate total pages
+- **Reporting**: Show record counts
+
+## Related Functions
+
+- [countset](./countset.md) - Count elements in a set
+- [countsetelements](./countsetelements.md) - Count unique elements
+- [sum](./sum.md) - Sum values instead of counting
+- [avg](./avg.md) - Average (uses count internally)
+
+## Notes
+
+- Returns result as string
+- Works with the Math service's `count` method
+- Returns "0" for empty arrays

package/user-documentation/solverfunctions/countset.md

@@ -0,0 +1,65 @@
+# countset
+
+Returns the count of elements in a set.
+
+## Syntax
+
+```
+countset(set)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `set` | Array | The set to count elements from |
+
+## Returns
+
+String - The number of elements in the set.
+
+## Description
+
+The `countset` function returns the number of elements in a set. It works similarly to `count` but is specifically designed for set operations.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = COUNTSET([1, 2, 3, 4, 5])
+// Result: "5"
+```
+
+### With Data
+
+```expression
+// Count items in a set
+TotalItems = COUNTSET(AppData.UniqueCategories)
+```
+
+### After Set Operations
+
+```expression
+// Count after concatenating sets
+CombinedCount = COUNTSET(SETCONCATENATE(Set1, Set2))
+```
+
+## Use Cases
+
+- **Set operations**: Determine set cardinality
+- **Data analysis**: Count unique values
+- **Validation**: Verify set sizes
+- **Statistics**: Sample size from sets
+
+## Related Functions
+
+- [count](./count.md) - Count array elements
+- [countsetelements](./countsetelements.md) - Count unique elements
+- [setconcatenate](./setconcatenate.md) - Combine sets
+
+## Notes
+
+- Returns result as string
+- Works with the Math service's `count` method
+- Functionally similar to `count`