pict-section-formeditor 1.0.0

package/user-documentation/solverfunctions/exp.md

@@ -0,0 +1,74 @@
+# exp
+
+Calculates e raised to the power of a number.
+
+## Syntax
+
+```
+exp(exponent)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `exponent` | Number | The power to raise e to |
+
+## Returns
+
+Number - The value of e^exponent.
+
+## Description
+
+The `exp` function calculates e (Euler's number, approximately 2.71828) raised to the specified power. This is the inverse of the natural logarithm function.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = EXP(1)
+// Result: 2.718281828459045 (e)
+```
+
+### Exponential of Zero
+
+```expression
+Result = EXP(0)
+// Result: 1
+```
+
+### With Variables
+
+```expression
+GrowthFactor = EXP(Rate * Time)
+```
+
+### Inverse of log
+
+```expression
+// EXP and LOG are inverse functions
+Original = 2.5
+Transformed = EXP(LOG(Original))
+// Transformed ≈ 2.5
+```
+
+## Use Cases
+
+- **Growth models**: Exponential growth calculations
+- **Statistics**: Normal distribution calculations
+- **Finance**: Continuous compound interest
+- **Physics**: Decay and growth functions
+
+## Related Functions
+
+- [log](./log.md) - Inverse function (natural logarithm)
+- [euler](./euler.md) - Euler's number constant
+- [sqrt](./sqrt.md) - Square root
+
+## Notes
+
+- EXP(0) = 1
+- EXP(1) = e ≈ 2.71828
+- Uses JavaScript's `Math.exp` internally
+- Useful for exponential growth/decay calculations

package/user-documentation/solverfunctions/findfirstvaluebyexactmatch.md

@@ -0,0 +1,67 @@
+# findfirstvaluebyexactmatch
+
+Finds the first object in an array where a property exactly matches a value.
+
+## Syntax
+
+```
+findfirstvaluebyexactmatch(array, property, value)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | Array of objects to search |
+| `property` | String | Property name to match against |
+| `value` | Any | Value to match |
+
+## Returns
+
+Object - The first matching object, or undefined if not found.
+
+## Description
+
+The `findfirstvaluebyexactmatch` function searches through an array of objects and returns the first object where the specified property exactly matches the given value.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given array: [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]
+Result = FINDFIRSTVALUEBYEXACTMATCH(Users, "name", "Bob")
+// Result: { id: 2, name: "Bob" }
+```
+
+### Find by ID
+
+```expression
+User = FINDFIRSTVALUEBYEXACTMATCH(AppData.Users, "id", "U123")
+```
+
+### Product Lookup
+
+```expression
+Product = FINDFIRSTVALUEBYEXACTMATCH(Products, "sku", "WIDGET-001")
+```
+
+## Use Cases
+
+- **Lookups**: Find record by unique property
+- **Data retrieval**: Get specific object
+- **Validation**: Check if record exists
+- **Search**: Simple exact-match search
+
+## Related Functions
+
+- [findfirstvaluebystringincludes](./findfirstvaluebystringincludes.md) - Partial string match
+- [match](./match.md) - Regex pattern matching
+- [entryinset](./entryinset.md) - Check if value exists in set
+
+## Notes
+
+- Returns first match only
+- Case-sensitive matching
+- Returns undefined if not found
+- Uses the Utility service's `findFirstValueByExactMatch` method

package/user-documentation/solverfunctions/findfirstvaluebystringincludes.md

@@ -0,0 +1,67 @@
+# findfirstvaluebystringincludes
+
+Finds the first object where a property contains a substring.
+
+## Syntax
+
+```
+findfirstvaluebystringincludes(array, property, substring)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | Array of objects to search |
+| `property` | String | Property name to search in |
+| `substring` | String | Substring to search for |
+
+## Returns
+
+Object - The first matching object, or undefined if not found.
+
+## Description
+
+The `findfirstvaluebystringincludes` function searches through an array of objects and returns the first object where the specified property contains the given substring.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Given: [{ name: "Alice Smith" }, { name: "Bob Jones" }]
+Result = FINDFIRSTVALUEBYSTRINGINCLUDES(Users, "name", "Smith")
+// Result: { name: "Alice Smith" }
+```
+
+### Email Search
+
+```expression
+User = FINDFIRSTVALUEBYSTRINGINCLUDES(Users, "email", "@company.com")
+```
+
+### Description Search
+
+```expression
+Product = FINDFIRSTVALUEBYSTRINGINCLUDES(Products, "description", "wireless")
+```
+
+## Use Cases
+
+- **Fuzzy search**: Find by partial match
+- **Text search**: Search in text fields
+- **Filtering**: Find containing substring
+- **Lookups**: Partial name/ID matching
+
+## Related Functions
+
+- [findfirstvaluebyexactmatch](./findfirstvaluebyexactmatch.md) - Exact match
+- [match](./match.md) - Regex pattern matching
+- [entryinset](./entryinset.md) - Check membership
+
+## Notes
+
+- Case-sensitive by default
+- Returns first match only
+- Partial string matching
+- Uses the Utility service's `findFirstValueByStringIncludes` method

package/user-documentation/solverfunctions/flatten.md

@@ -0,0 +1,76 @@
+# flatten
+
+Flattens a nested array or extracts property values from an array of objects.
+
+## Syntax
+
+```
+flatten(array)
+flatten(arrayOfObjects.property)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `array` | Array | The array to flatten or property path to extract |
+
+## Returns
+
+Array - A flattened array of values.
+
+## Description
+
+The `flatten` function can flatten nested arrays into a single-level array, or extract all values of a specific property from an array of objects. This is essential for preparing data for aggregate functions.
+
+## Examples
+
+### Flatten Nested Arrays
+
+```expression
+Result = FLATTEN([[1, 2], [3, 4], [5]])
+// Result: [1, 2, 3, 4, 5]
+```
+
+### Extract Property Values
+
+```expression
+// Given AppData.Cities with objects containing 'population' property
+Populations = FLATTEN(AppData.Cities.population)
+// Result: [39538223, 29145505, 21538187, ...]
+```
+
+### With Aggregate Functions
+
+```expression
+// Sum all populations
+TotalPopulation = SUM(FLATTEN(AppData.Cities.population))
+```
+
+### Chain Operations
+
+```expression
+// Get average of extracted values
+AverageScore = AVG(FLATTEN(AppData.Students.score))
+```
+
+## Use Cases
+
+- **Data extraction**: Get property values from object arrays
+- **Array processing**: Flatten nested structures
+- **Aggregation prep**: Prepare data for SUM, AVG, etc.
+- **Data transformation**: Restructure array data
+
+## Related Functions
+
+- [sum](./sum.md) - Sum flattened values
+- [avg](./avg.md) - Average flattened values
+- [objectkeystoarray](./objectkeystoarray.md) - Extract object keys
+- [objectvaluestoarray](./objectvaluestoarray.md) - Extract object values
+
+## Notes
+
+- Critical for preparing data for aggregate functions
+- Works with both nested arrays and object arrays
+- Uses the Math service's `flatten` method
+- Commonly used in data pipelines

package/user-documentation/solverfunctions/floor.md

@@ -0,0 +1,70 @@
+# floor
+
+Returns the largest integer less than or equal to a number.
+
+## Syntax
+
+```
+floor(value)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | Number/String | The value to floor |
+
+## Returns
+
+String - The largest integer less than or equal to the input.
+
+## Description
+
+The `floor` function rounds a number down to the nearest integer. For positive numbers, this truncates the decimal portion. For negative numbers, it rounds away from zero (more negative).
+
+## Examples
+
+### Basic Usage
+
+```expression
+Result = floor(3.7)
+// Result: "3"
+
+Result = floor(3.2)
+// Result: "3"
+
+Result = floor(3.0)
+// Result: "3"
+
+Result = floor(-2.3)
+// Result: "-3" (rounds toward negative infinity)
+```
+
+### With Expressions
+
+```expression
+// Get the integer part of a calculation
+WholeUnits = floor(TotalAmount / UnitPrice)
+
+// Determine array index from position
+Index = floor(Position / ItemSize)
+```
+
+## Use Cases
+
+- **Integer division**: Getting the quotient without remainder
+- **Array indexing**: Converting continuous values to discrete indices
+- **Pagination**: Calculating page numbers
+- **Time calculations**: Converting decimal hours to whole hours
+
+## Related Functions
+
+- [ceil](./ceil.md) - Round up (ceiling)
+- [round](./round.md) - Round to nearest
+- [tofixed](./tofixed.md) - Format to fixed decimal places
+
+## Notes
+
+- Uses arbitrary precision arithmetic
+- Returns a string representation
+- For negative numbers, floor(-2.3) = -3, not -2

package/user-documentation/solverfunctions/gaussianelimination.md

@@ -0,0 +1,75 @@
+# gaussianelimination
+
+Solves a system of linear equations using Gaussian elimination.
+
+## Syntax
+
+```
+gaussianelimination(coefficientMatrix, constantVector)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `coefficientMatrix` | Array | Matrix of coefficients (n×n) |
+| `constantVector` | Array | Vector of constants (length n) |
+
+## Returns
+
+Array - Solution vector.
+
+## Description
+
+The `gaussianelimination` function solves a system of linear equations Ax = b using Gaussian elimination with back substitution.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Solve:
+// 2x + y = 5
+// x + 3y = 10
+
+A = [[2, 1], [1, 3]]
+b = [5, 10]
+Solution = GAUSSIANELIMINATION(A, b)
+// Result: [1, 3] meaning x=1, y=3
+```
+
+### 3x3 System
+
+```expression
+// Three equations with three unknowns
+Coefficients = [[1, 2, 1], [2, 6, 1], [1, 1, 4]]
+Constants = [2, 7, 3]
+Solution = GAUSSIANELIMINATION(Coefficients, Constants)
+```
+
+### Engineering Problem
+
+```expression
+// Solve circuit/structure equations
+Values = GAUSSIANELIMINATION(SystemMatrix, LoadVector)
+```
+
+## Use Cases
+
+- **Engineering**: Structural analysis
+- **Physics**: Equilibrium problems
+- **Economics**: Input-output models
+- **Optimization**: Constraint systems
+
+## Related Functions
+
+- [matrixinverse](./matrixinverse.md) - Alternative via inverse
+- [matrixmultiply](./matrixmultiply.md) - Verify solutions
+- [leastsquares](./leastsquares.md) - Overdetermined systems
+
+## Notes
+
+- Efficient for dense systems
+- Handles n×n systems
+- May have numerical precision limits
+- Uses the Math service's `gaussianElimination` method

package/user-documentation/solverfunctions/generatearrayofobjectsfromsets.md

@@ -0,0 +1,70 @@
+# generatearrayofobjectsfromsets
+
+Generates an array of objects from parallel arrays.
+
+## Syntax
+
+```
+generatearrayofobjectsfromsets(keys, valueArrays)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `keys` | Array | Array of property names |
+| `valueArrays` | Array | Array of value arrays |
+
+## Returns
+
+Array - Array of objects with properties from keys and values from arrays.
+
+## Description
+
+The `generatearrayofobjectsfromsets` function creates an array of objects by combining property names with parallel arrays of values. Each object gets its properties from corresponding positions in the value arrays.
+
+## Examples
+
+### Basic Usage
+
+```expression
+Keys = ["name", "age"]
+Names = ["Alice", "Bob", "Carol"]
+Ages = [25, 30, 35]
+
+Result = GENERATEARRAYOFOBJECTSFROMSETS(Keys, [Names, Ages])
+// Result: [
+//   { name: "Alice", age: 25 },
+//   { name: "Bob", age: 30 },
+//   { name: "Carol", age: 35 }
+// ]
+```
+
+### From CSV Columns
+
+```expression
+Headers = ["id", "product", "price"]
+Column1 = ["001", "002", "003"]
+Column2 = ["Widget", "Gadget", "Thing"]
+Column3 = [9.99, 19.99, 4.99]
+
+Records = GENERATEARRAYOFOBJECTSFROMSETS(Headers, [Column1, Column2, Column3])
+```
+
+## Use Cases
+
+- **Data transformation**: Convert columnar to row data
+- **CSV processing**: Build objects from columns
+- **Parallel arrays**: Combine related arrays
+- **Data generation**: Create structured data
+
+## Related Functions
+
+- [createvalueobjectbyhashes](./createvalueobjectbyhashes.md) - Create single object
+- [objectkeystoarray](./objectkeystoarray.md) - Extract keys
+- [flatten](./flatten.md) - Flatten arrays
+
+## Notes
+
+- Value arrays should have same length
+- Uses the Math service's `generateArrayOfObjectsFromSets` method

package/user-documentation/solverfunctions/generatehtmlhexcolor.md

@@ -0,0 +1,67 @@
+# generatehtmlhexcolor
+
+Generates an HTML hex color string from RGB components.
+
+## Syntax
+
+```
+generatehtmlhexcolor(red, green, blue)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `red` | Integer | Red component, 0-255 |
+| `green` | Integer | Green component, 0-255 |
+| `blue` | Integer | Blue component, 0-255 |
+
+## Returns
+
+A string containing the HTML hex color code (e.g., `"#FF0000"`).
+
+## Description
+
+The `generatehtmlhexcolor` function takes three integer values representing the red, green, and blue components of a color and returns the corresponding HTML hex color string. Each component should be an integer between 0 and 255. The returned string is in the format `#RRGGBB` and can be used with color-related form functions such as `colorsectionbackground`, `colorgroupbackground`, and `colorinputbackground`.
+
+## Examples
+
+### Generating an orange color
+
+```expression
+Color = generatehtmlhexcolor(255, 128, 0)
+// Color is "#FF8000"
+```
+
+### Generating red
+
+```expression
+Red = generatehtmlhexcolor(255, 0, 0)
+// Red is "#FF0000"
+```
+
+### Using calculated color values
+
+```expression
+Intensity = Score * 255 / 100
+BarColor = generatehtmlhexcolor(Intensity, 255 - Intensity, 0)
+// Produces a color ranging from green (low score) to red (high score)
+```
+
+## Use Cases
+
+- **Dynamic coloring**: Generate colors based on calculated values for use in form styling
+- **Data visualization**: Map numeric values to colors for visual feedback in forms
+- **Conditional formatting**: Create color values dynamically based on form state
+
+## Related Functions
+
+- [colorsectionbackground](./colorsectionbackground.md) - Sets the background color of a form section
+- [colorgroupbackground](./colorgroupbackground.md) - Sets the background color of a form group
+- [colorinputbackground](./colorinputbackground.md) - Sets the background color of a form input
+
+## Notes
+
+- Each RGB component should be an integer between 0 and 255
+- Values outside the 0-255 range may produce unexpected results
+- The returned string includes the `#` prefix

package/user-documentation/solverfunctions/getvalue.md

@@ -0,0 +1,90 @@
+# getvalue
+
+Retrieves a value from application state using a hash/path address.
+
+## Syntax
+
+```
+getvalue(path)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `path` | String | Dot-notation path to the value (in quotes) |
+
+## Returns
+
+The value at the specified path, or `undefined` if not found.
+
+## Description
+
+The `getvalue` function retrieves values from the Fable application state (AppData, services, etc.) using a dot-notation path. This allows expressions to access data stored elsewhere in the application.
+
+## Examples
+
+### Basic Usage
+
+```expression
+// Access a simple value
+PitSize = getvalue("AppData.Pit")
+// If AppData.Pit = "Bottomless"
+// Result: "Bottomless"
+```
+
+### Array Access
+
+```expression
+// Access array elements
+FirstStudent = GETVALUE("AppData.Students[0]")
+// If AppData.Students = ["Kim", "Jim", "Joan Jett", "Tank Girl"]
+// Result: "Kim"
+
+ThirdStudent = GETVALUE("AppData.Students[2]")
+// Result: "Joan Jett"
+```
+
+### Nested Object Access
+
+```expression
+// Access nested properties
+CityName = getvalue("AppData.Cities[0].city")
+// If AppData.Cities[0] = { city: "New York", state: "New York" }
+// Result: "New York"
+```
+
+### With Null Coalescence Assignment
+
+```expression
+// Only assign if target doesn't already have a value
+Name ?= GETVALUE("AppData.Students[0]")
+// Sets Name to "Kim" only if Name is currently empty/undefined
+```
+
+### In Complex Expressions
+
+```expression
+// Combine with other functions
+Histogram = aggregationhistogrambyobject(getvalue("AppData.Teams"), "States", "Score")
+```
+
+## Use Cases
+
+- **Configuration access**: Reading application settings
+- **Data lookup**: Retrieving stored values
+- **Dynamic references**: Access paths determined at runtime
+- **Cross-module data**: Sharing data between components
+
+## Related Functions
+
+- [getvaluearray](./getvaluearray.md) - Get array of values
+- [getvalueobject](./getvalueobject.md) - Get object of values
+
+## Notes
+
+- The path must be quoted (it's a string)
+- Accesses `fable.Utility.getInternalValueByHash`
+- Returns `undefined` if the path doesn't exist
+- Array indices use bracket notation: `[0]`, `[1]`, etc.
+- Works with any data stored on the Fable instance