pict-section-formeditor 1.0.11 → 1.0.13

package/docs/_sidebar.md

@@ -17,6 +17,20 @@
 	- [Reading the Manifest](#/README?id=reading-the-manifest-back)
 	- [Architecture](#/README?id=architecture)
 
+- User Documentation
+	- [Table of Contents](user-docs/ToC.md)
+	- [Getting Started](user-docs/Getting-Started.md)
+	- [Sections](user-docs/Sections.md)
+	- [Groups](user-docs/Groups.md)
+	- [Inputs & Data Types](user-docs/Inputs.md)
+	- [Solvers](user-docs/Solvers.md)
+	- [Keyboard Shortcuts](user-docs/Shortcuts.md)
+
+- Solver Expression Guides
+	- [Solver Expression Walkthrough](user-docs/Solver-Expression-Walkthrough.md)
+	- [Solver Expressions Advanced Topics](user-docs/Solver-Expressions-Advanced.md)
+	- [Solver Functions Reference](user-docs/Solver-Functions.md)
+
 - Resources
 	- [Example Application](#/README?id=example-application)
 	- [GitHub](https://github.com/stevenvelozo/pict-section-formeditor)

package/{user-documentation → docs/user-docs}/pict_documentation_topics.json

@@ -636,60 +636,52 @@
 	},
 	"SLV-OP-Add": {
 		"TopicCode": "SLV-OP-Add",
-		"TopicHelpFilePath": "Solver-Expression-Walkthrough.md",
-		"TopicTitle": "Addition Operator (+)",
-		"RelevantMarkdownLine": 39
+		"TopicHelpFilePath": "solveroperators/add.md",
+		"TopicTitle": "Addition Operator (+)"
 	},
 	"SLV-OP-Subtract": {
 		"TopicCode": "SLV-OP-Subtract",
-		"TopicHelpFilePath": "Solver-Expression-Walkthrough.md",
-		"TopicTitle": "Subtraction Operator (-)",
-		"RelevantMarkdownLine": 40
+		"TopicHelpFilePath": "solveroperators/subtract.md",
+		"TopicTitle": "Subtraction Operator (-)"
 	},
 	"SLV-OP-Multiply": {
 		"TopicCode": "SLV-OP-Multiply",
-		"TopicHelpFilePath": "Solver-Expression-Walkthrough.md",
-		"TopicTitle": "Multiplication Operator (*)",
-		"RelevantMarkdownLine": 36
+		"TopicHelpFilePath": "solveroperators/multiply.md",
+		"TopicTitle": "Multiplication Operator (*)"
 	},
 	"SLV-OP-Divide": {
 		"TopicCode": "SLV-OP-Divide",
-		"TopicHelpFilePath": "Solver-Expression-Walkthrough.md",
-		"TopicTitle": "Division Operator (/)",
-		"RelevantMarkdownLine": 37
+		"TopicHelpFilePath": "solveroperators/divide.md",
+		"TopicTitle": "Division Operator (/)"
 	},
 	"SLV-OP-Modulus": {
 		"TopicCode": "SLV-OP-Modulus",
-		"TopicHelpFilePath": "Solver-Expression-Walkthrough.md",
-		"TopicTitle": "Modulus Operator (%)",
-		"RelevantMarkdownLine": 38
+		"TopicHelpFilePath": "solveroperators/modulus.md",
+		"TopicTitle": "Modulus Operator (%)"
 	},
 	"SLV-OP-Exponent": {
 		"TopicCode": "SLV-OP-Exponent",
-		"TopicHelpFilePath": "Solver-Expression-Walkthrough.md",
-		"TopicTitle": "Exponentiation Operator (^)",
-		"RelevantMarkdownLine": 35
+		"TopicHelpFilePath": "solveroperators/exponent.md",
+		"TopicTitle": "Exponentiation Operator (^)"
 	},
 	"SLV-OP-SetConcat": {
 		"TopicCode": "SLV-OP-SetConcat",
-		"TopicHelpFilePath": "Solver-Functions.md",
+		"TopicHelpFilePath": "solveroperators/setconcat.md",
 		"TopicTitle": "Set Concatenation Operator (,)"
 	},
 	"SLV-ASSIGN-Equals": {
 		"TopicCode": "SLV-ASSIGN-Equals",
-		"TopicHelpFilePath": "Solver-Expression-Walkthrough.md",
-		"TopicTitle": "Assignment Operator (=)",
-		"RelevantMarkdownLine": 17
+		"TopicHelpFilePath": "solveroperators/assign.md",
+		"TopicTitle": "Assignment Operator (=)"
 	},
 	"SLV-ASSIGN-NullCoalesce": {
 		"TopicCode": "SLV-ASSIGN-NullCoalesce",
-		"TopicHelpFilePath": "Solver-Expression-Walkthrough.md",
-		"TopicTitle": "Null Coalescence Assignment (?=)",
-		"RelevantMarkdownLine": 141
+		"TopicHelpFilePath": "solveroperators/nullcoalesce.md",
+		"TopicTitle": "Null Coalescence Assignment (?=)"
 	},
 	"SLV-ASSIGN-ExpressionBegin": {
 		"TopicCode": "SLV-ASSIGN-ExpressionBegin",
-		"TopicHelpFilePath": "Solver-Expressions-Advanced.md",
+		"TopicHelpFilePath": "solveroperators/expressionbegin.md",
 		"TopicTitle": "Expression Begin Directive (:)"
 	}
 }

package/docs/user-docs/solveroperators/add.md

@@ -0,0 +1,75 @@
+# Addition Operator (+)
+
+Adds two numeric values together.
+
+## Syntax
+
+```
+left + right
+```
+
+## Description
+
+The `+` operator performs addition on two numeric operands. It uses arbitrary precision arithmetic, so results are accurate even for very large or very small numbers.
+
+When used in a solver expression, the `+` operator is one of the standard arithmetic operators and has lower precedence than `*`, `/`, `%`, and `^`.
+
+## Precedence
+
+The `+` operator has the same precedence as `-` (subtraction). Both are evaluated after `*`, `/`, `%`, and `^`. Use parentheses to override the default order.
+
+| Precedence | Operators |
+|------------|-----------|
+| Highest | `^` |
+| | `*` `/` `%` |
+| Lowest | `+` `-` |
+
+## Examples
+
+### Basic Addition
+
+```expression
+Total = Price + Tax
+// With Price = 100, Tax = 8.50
+// Result: "108.50"
+```
+
+### Chaining Multiple Additions
+
+```expression
+GrandTotal = Subtotal + Tax + ShippingFee
+```
+
+### Combined with Other Operators
+
+```expression
+// Multiplication is evaluated before addition
+Result = Price + Tax * Quantity
+// Equivalent to: Price + (Tax * Quantity)
+
+// Use parentheses to add first
+Result = (Price + Tax) * Quantity
+```
+
+### Adding Constants
+
+```expression
+AdjustedScore = RawScore + 10
+```
+
+## Related Operators
+
+- [-](./subtract.md) - Subtraction
+- [*](./multiply.md) - Multiplication
+- [/](./divide.md) - Division
+
+## Related Functions
+
+- [sum](../solverfunctions/sum.md) - Sum all values in an array
+- [round](../solverfunctions/round.md) - Round a computed result
+
+## Notes
+
+- Uses arbitrary precision arithmetic
+- Non-numeric operands may produce unexpected results
+- The result is always returned as a string

package/docs/user-docs/solveroperators/assign.md

@@ -0,0 +1,83 @@
+# Assignment Operator (=)
+
+Assigns the result of the right-hand expression to the left-hand target.
+
+## Syntax
+
+```
+target = expression
+```
+
+## Description
+
+The `=` operator is the assignment operator in solver expressions. It evaluates the expression on the right side and stores the result in the variable or form input identified by the left side.
+
+The left-hand target can be:
+- A form input hash (writes the result to that input)
+- A temporary variable name (stores a value for use in later expressions)
+
+## Examples
+
+### Assigning to a Form Input
+
+```expression
+Area = Height * Width
+// Computes Height * Width and writes the result to the input with hash "Area"
+```
+
+### Assigning a Constant
+
+```expression
+DefaultRate = 0.05
+// Sets DefaultRate to 0.05
+```
+
+### Assigning a Computed Value
+
+```expression
+Tax = round(Subtotal * TaxRate, 2)
+```
+
+### Assigning a String
+
+```expression
+Status = if(Total, ">=", 1000, "High Value", "Standard")
+```
+
+### Using Temporary Variables
+
+```expression
+// Solver ordinal 1: compute intermediates
+TempSubtotal = Price * Quantity
+TempTax = round(TempSubtotal * 0.08, 2)
+
+// Solver ordinal 2: compute final values using intermediates
+GrandTotal = TempSubtotal + TempTax
+```
+
+### Expressions Without Assignment
+
+Not all expressions need an assignment. Some functions perform side effects directly:
+
+```expression
+// These call functions without storing a return value
+SetGroupVisibility("Products", "Details", if(ShowDetails, "==", 1, 1, 0))
+ColorSectionBackground("Summary", "#E0F0E0", 1)
+```
+
+## Related Operators
+
+- [?=](./nullcoalesce.md) - Null coalescence assignment (assign only if target is empty)
+- [:](./expressionbegin.md) - Expression begin directive
+
+## Related Topics
+
+- [Solver Expression Walkthrough](../Solver-Expression-Walkthrough.md) - Expression basics
+- [Solvers](../Solvers.md) - How solvers execute
+
+## Notes
+
+- The left-hand target is case-sensitive
+- If the target matches a form input hash, the computed value is written to that input
+- If the target does not match any input, it is treated as a temporary variable
+- The `=` operator is evaluated after all arithmetic and function calls on the right side

package/docs/user-docs/solveroperators/divide.md

@@ -0,0 +1,73 @@
+# Division Operator (/)
+
+Divides the left operand by the right operand.
+
+## Syntax
+
+```
+left / right
+```
+
+## Description
+
+The `/` operator performs division on two numeric operands. It uses arbitrary precision arithmetic for accurate results. Division by zero returns `0` rather than causing an error.
+
+## Precedence
+
+The `/` operator has the same precedence as `*` (multiplication) and `%` (modulus). All three are evaluated before `+` and `-`, but after `^` (exponentiation).
+
+| Precedence | Operators |
+|------------|-----------|
+| Highest | `^` |
+| | `*` `/` `%` |
+| Lowest | `+` `-` |
+
+## Examples
+
+### Basic Division
+
+```expression
+Average = Total / Count
+// With Total = 250, Count = 5
+// Result: "50"
+```
+
+### Percentage Calculation
+
+```expression
+PercentComplete = CompletedItems / TotalItems * 100
+```
+
+### With Rounding
+
+```expression
+// Division can produce many decimal places; round for display
+Rate = round(Amount / Hours, 2)
+// With Amount = 1000, Hours = 3
+// Result: "333.33"
+```
+
+### In a Complex Expression
+
+```expression
+// Compute a weighted average
+WeightedAvg = (Score1 * Weight1 + Score2 * Weight2) / (Weight1 + Weight2)
+```
+
+## Related Operators
+
+- [*](./multiply.md) - Multiplication
+- [%](./modulus.md) - Modulus (remainder)
+- [^](./exponent.md) - Exponentiation
+
+## Related Functions
+
+- [round](../solverfunctions/round.md) - Round a computed result
+- [avg](../solverfunctions/avg.md) - Compute average of an array
+
+## Notes
+
+- Uses arbitrary precision arithmetic
+- Division by zero returns `0` (no error is thrown)
+- The result is always returned as a string
+- For long decimal results, use `round` or `tofixed` to limit precision

package/docs/user-docs/solveroperators/exponent.md

@@ -0,0 +1,83 @@
+# Exponentiation Operator (^)
+
+Raises the left operand to the power of the right operand.
+
+## Syntax
+
+```
+base ^ exponent
+```
+
+## Description
+
+The `^` operator raises a base value to a given power. It uses arbitrary precision arithmetic for accurate results. This is the highest-precedence arithmetic operator.
+
+## Precedence
+
+The `^` operator has the highest precedence among arithmetic operators. It is evaluated before all others.
+
+| Precedence | Operators |
+|------------|-----------|
+| Highest | `^` |
+| | `*` `/` `%` |
+| Lowest | `+` `-` |
+
+## Examples
+
+### Basic Exponentiation
+
+```expression
+Squared = Value ^ 2
+// With Value = 5
+// Result: "25"
+```
+
+### Cubing a Value
+
+```expression
+Cubed = Side ^ 3
+// With Side = 4
+// Result: "64"
+```
+
+### Square Root via Fractional Exponent
+
+```expression
+// Square root is the same as raising to the power of 0.5
+SquareRoot = Value ^ 0.5
+// With Value = 16
+// Result: "4"
+```
+
+### In a Complex Expression
+
+```expression
+// Exponentiation is evaluated first
+WidthCubeArea = Width ^ 3
+HeightCubeArea = Height ^ 3
+```
+
+### Combined with Other Operators
+
+```expression
+// ^ is evaluated before * and +
+Result = 2 + 3 ^ 2 * 4
+// Equivalent to: 2 + (9 * 4) = 2 + 36 = 38
+```
+
+## Related Operators
+
+- [*](./multiply.md) - Multiplication
+- [/](./divide.md) - Division
+
+## Related Functions
+
+- [sqrt](../solverfunctions/sqrt.md) - Square root
+- [round](../solverfunctions/round.md) - Round a computed result
+
+## Notes
+
+- Uses arbitrary precision arithmetic
+- The result is always returned as a string
+- Fractional exponents compute roots (e.g. `^ 0.5` for square root)
+- Has the highest precedence of all arithmetic operators

package/docs/user-docs/solveroperators/expressionbegin.md

@@ -0,0 +1,61 @@
+# Expression Begin Directive (:)
+
+Marks the beginning of an inline expression within a MAP or VAR pipeline.
+
+## Syntax
+
+```
+MAP VAR name FROM source : expression
+```
+
+## Description
+
+The `:` operator signals the start of the expression body in a `MAP ... VAR ... FROM ...` pipeline. Everything after the `:` is the expression that gets evaluated for each element in the source data.
+
+The `:` is used exclusively in MAP expressions and is not a general-purpose operator.
+
+## Examples
+
+### Basic MAP Expression
+
+```expression
+// Double each value in a set
+Doubled = MAP VAR x FROM Values : x * 2
+```
+
+### MAP with Multiple Variables
+
+```expression
+// Combine values from two parallel arrays
+Combined = MAP VAR a FROM Prices VAR b FROM Quantities : a * b
+```
+
+### MAP with Conditional Logic
+
+```expression
+// Apply different logic per element
+Adjusted = MAP VAR val FROM RawScores : if(val, ">", 100, 100, val)
+```
+
+### In a Complex Pipeline
+
+```expression
+// Map, then aggregate
+ItemTotals = MAP VAR price FROM Prices VAR qty FROM Quantities : price * qty
+GrandTotal = SUM(ItemTotals)
+```
+
+## Related Operators
+
+- [=](./assign.md) - Assignment operator
+- [,](./setconcat.md) - Set concatenation (argument separator)
+
+## Related Topics
+
+- [Solver Expressions Advanced Topics](../Solver-Expressions-Advanced.md) - MAP, VAR, FROM details
+
+## Notes
+
+- The `:` must appear after all VAR/FROM declarations in a MAP expression
+- Everything after the `:` is the per-element expression
+- The result of the MAP expression is an array of the computed values

package/docs/user-docs/solveroperators/modulus.md

@@ -0,0 +1,70 @@
+# Modulus Operator (%)
+
+Returns the remainder after dividing the left operand by the right operand.
+
+## Syntax
+
+```
+left % right
+```
+
+## Description
+
+The `%` operator computes the modulus (remainder) of dividing the left operand by the right operand. It uses arbitrary precision arithmetic.
+
+## Precedence
+
+The `%` operator has the same precedence as `*` (multiplication) and `/` (division). All three are evaluated before `+` and `-`, but after `^` (exponentiation).
+
+| Precedence | Operators |
+|------------|-----------|
+| Highest | `^` |
+| | `*` `/` `%` |
+| Lowest | `+` `-` |
+
+## Examples
+
+### Basic Modulus
+
+```expression
+Remainder = 7 % 3
+// Result: "1"
+```
+
+### Check for Even/Odd
+
+```expression
+// Use if() to test the remainder
+Parity = if(Value % 2, "==", 0, "Even", "Odd")
+```
+
+### Cyclic Index
+
+```expression
+// Wrap an index into a fixed range (e.g. 0-11 for months)
+MonthIndex = RawMonth % 12
+```
+
+### Combined with Division
+
+```expression
+// Get whole part and remainder separately
+WholePart = floor(Total / GroupSize)
+LeftOver = Total % GroupSize
+```
+
+## Related Operators
+
+- [/](./divide.md) - Division
+- [*](./multiply.md) - Multiplication
+
+## Related Functions
+
+- [floor](../solverfunctions/floor.md) - Round down to integer
+- [round](../solverfunctions/round.md) - Round a computed result
+
+## Notes
+
+- Uses arbitrary precision arithmetic
+- The result is always returned as a string
+- The sign of the result matches the sign of the left operand

package/docs/user-docs/solveroperators/multiply.md

@@ -0,0 +1,79 @@
+# Multiplication Operator (*)
+
+Multiplies two numeric values together.
+
+## Syntax
+
+```
+left * right
+```
+
+## Description
+
+The `*` operator performs multiplication on two numeric operands. It uses arbitrary precision arithmetic for accurate results, even with very large numbers or many decimal places.
+
+## Precedence
+
+The `*` operator has the same precedence as `/` (division) and `%` (modulus). All three are evaluated before `+` and `-`, but after `^` (exponentiation).
+
+| Precedence | Operators |
+|------------|-----------|
+| Highest | `^` |
+| | `*` `/` `%` |
+| Lowest | `+` `-` |
+
+## Examples
+
+### Basic Multiplication
+
+```expression
+Area = Height * Width
+// With Height = 12, Width = 8
+// Result: "96"
+```
+
+### Computing a Product with Multiple Factors
+
+```expression
+Volume = Length * Width * Height
+```
+
+### Combined with Addition
+
+```expression
+// Multiplication is evaluated before addition
+Total = BasePrice + TaxRate * BasePrice
+// Equivalent to: BasePrice + (TaxRate * BasePrice)
+```
+
+### Using Parentheses
+
+```expression
+// Force addition before multiplication
+Result = (Price + Tax) * Quantity
+```
+
+### With Rounding
+
+```expression
+// Multiply and round to 2 decimal places
+Cost = round(UnitPrice * Quantity, 2)
+```
+
+## Related Operators
+
+- [/](./divide.md) - Division
+- [^](./exponent.md) - Exponentiation
+- [+](./add.md) - Addition
+- [-](./subtract.md) - Subtraction
+
+## Related Functions
+
+- [round](../solverfunctions/round.md) - Round a computed result
+- [tofixed](../solverfunctions/tofixed.md) - Format to fixed decimal places
+
+## Notes
+
+- Uses arbitrary precision arithmetic
+- Non-numeric operands may produce unexpected results
+- The result is always returned as a string