pict-section-formeditor 1.0.0

package/user-documentation/Getting-Started.md

@@ -0,0 +1,32 @@
+# Getting Started
+
+The Form Editor is a visual tool for building and editing pict-section-form configuration manifests. A manifest describes the structure of a form: its sections, groups, inputs, data types, and solver expressions.
+
+## The Editor Layout
+
+The editor is divided into two main areas:
+
+- **Visual Editor** (left) -- The main canvas where you build your form by adding sections, groups, and inputs. You can click on any element to select it and edit its properties.
+- **Properties Panel** (right) -- A collapsible panel with tabs for editing the selected element. Switch between Form, Section, Group, Input, Options, and Help tabs.
+
+## Building a Form
+
+1. **Add a Section** -- Click the "Add Section" button in the visual editor toolbar. Every form needs at least one section.
+2. **Add a Group** -- Within a section, click "Add Group" to create an input group. Groups organize related inputs together.
+3. **Add Inputs** -- Inside a group, click "Add Input" to create form fields. Each input has a name, data type, and input type.
+4. **Configure Properties** -- Click on any section, group, or input to select it. Its properties will appear in the Properties Panel on the right.
+
+## Tabs
+
+The main editor has several tabs across the top:
+
+- **Visual** -- The drag-and-drop form builder
+- **Solver Editor** -- Edit solver expressions for computed fields
+- **Solvers** -- View all solver expressions at a glance
+- **JSON** -- View and edit the raw manifest JSON
+
+## Next Steps
+
+- Learn about [Sections](Sections.md) to understand form structure
+- Explore [Solvers](Solvers.md) to add computed values
+- Return to the [Table of Contents](ToC.md) for all topics

package/user-documentation/Groups.md

@@ -0,0 +1,52 @@
+# Groups
+
+Groups organize related inputs within a section. Each section contains one or more groups, and each group contains rows of inputs.
+
+## Creating a Group
+
+Click the **Add Group** button inside a section in the visual editor. A new group is created with an auto-generated hash based on the section (e.g. "S1_G2") and a default Record layout.
+
+## Group Properties
+
+Select a group by clicking its icon in the visual editor or choosing it from the Group tab's searchable dropdown in the properties panel. The following properties are available:
+
+- **Name** -- The display label for the group (e.g. "Contact Details"). Click the name in the visual editor to edit it inline.
+- **Hash** -- A unique identifier (e.g. "S1_G1"). Click the hash in the visual editor to edit it inline.
+- **Layout** -- The group's layout strategy. Click the layout label in the visual editor to change it via a dropdown, or use the Group tab in the properties panel.
+- **CSSClass** -- A CSS class name for styling the group container.
+
+## Layout Types
+
+Groups support three layout modes:
+
+### Record
+
+The default layout. Each row in the group displays a single record's worth of inputs side by side. This is the standard layout for most forms.
+
+### Tabular
+
+A multi-column grid layout for displaying data in a table format. Tabular groups have additional properties:
+
+- **RecordSetAddress** -- The AppData path to the data array (e.g. `FruitData.FruityVice`).
+- **RecordManifest** -- A reference to an external manifest that defines the columns.
+- **RecordSetSolvers** -- Solver expressions that apply to each record in the set.
+
+The properties panel shows a summary of the referenced manifest, including column count and data types.
+
+### RecordSet
+
+A multi-row layout for displaying and editing sets of records. Similar to Tabular, it uses a sub-manifest to define the structure of each record. RecordSet groups share the same additional properties as Tabular groups.
+
+## Reordering Groups
+
+Use the arrow buttons on the group header in the visual editor to move groups up or down within their section. When drag-and-drop is enabled, groups can be dragged within a section or across sections.
+
+## Deleting a Group
+
+Click the delete button on the group header. This removes the group, its rows, and all contained inputs.
+
+## Next Steps
+
+- Learn about [Inputs & Data Types](Inputs.md) to add fields to your groups
+- Return to [Sections](Sections.md) for the broader form structure
+- Return to the [Table of Contents](ToC.md)

package/user-documentation/Inputs.md

@@ -0,0 +1,98 @@
+# Inputs & Data Types
+
+Inputs are the individual form fields that users interact with. Each input has a data type that defines what kind of value it stores and an input type that controls how it is rendered.
+
+## Creating an Input
+
+Click the **Add Input** button inside a row in the visual editor. A new input is created with a default String data type and no input type. You can also add rows to a group using the **Add Row** button, which creates a new horizontal row that can hold multiple inputs side by side.
+
+## Input Properties
+
+Select an input by clicking it in the visual editor. Its properties appear in the Input tab of the properties panel:
+
+- **Name** -- The display label shown to the user (e.g. "Email Address").
+- **Hash** -- A unique identifier for this input within the manifest.
+- **Address** -- The data path that binds this input to a value in AppData (e.g. `UserProfile.Email`). Changing the address re-keys the input in the manifest. A confirmation step prevents accidental changes.
+- **DataType** -- The underlying data type for this field (see Data Types below).
+- **InputType** -- The rendering and interaction style (see Input Types below). Click the InputType button to open a searchable picker.
+- **Width** -- Grid width from 1 to 12 columns for responsive layout.
+
+## Data Types
+
+Each input stores a value with one of the following data types:
+
+- **String** -- Text values (the default)
+- **Number** -- Numeric values
+- **Float** -- Floating-point numbers
+- **Integer** -- Whole numbers
+- **PreciseNumber** -- High-precision decimal values
+- **Boolean** -- True or false
+- **Binary** -- Binary data
+- **DateTime** -- Date and time values
+- **Array** -- Ordered lists of values
+- **Object** -- Key-value data structures
+- **Null** -- Null/empty value
+
+Change the data type from the Input tab dropdown or by clicking the data type label directly in the visual editor.
+
+## Input Types
+
+Input types control how a field is rendered and how the user interacts with it. They are organized into categories:
+
+### Text & Content
+
+- **TextArea** -- Multi-line text input
+- **Markdown** -- Markdown-formatted text editor
+- **HTML** -- Rich HTML content block
+
+### Selection
+
+- **Option** -- Dropdown select from a set of choices. Has additional properties:
+  - *Select Options* -- A JSON array of `{id, text}` option objects
+  - *Pick List Name* -- A named dynamic pick list from AppData
+- **Boolean** -- Checkbox or toggle for true/false values
+- **Color** -- Color picker input
+
+### Display
+
+- **Display Only** -- Read-only display of the value with no input control
+- **Read Only** -- Input-styled read-only field
+- **Precise Number (Read Only)** -- Formatted number display with additional properties:
+  - *Decimal Precision* -- Number of decimal places
+  - *Add Commas* -- Thousand-separator formatting
+  - *Prefix* -- String prepended to the value (e.g. "$")
+  - *Postfix* -- String appended to the value (e.g. " USD")
+- **Hidden** -- Hidden input, not visible to the user
+- **Chart** -- Data visualization with additional properties:
+  - *Chart Type* -- The chart style (bar, line, pie, doughnut, radar, polarArea)
+  - *Labels Address* -- AppData path for chart labels
+  - *Labels Solver* -- Solver expression for chart labels
+  - *Datasets Address* -- AppData path for chart datasets
+- **Link** -- Clickable hyperlink display
+
+### Navigation
+
+- **Tab Section Selector** -- Controls which sections display as tabs. Properties:
+  - *Section Set* -- JSON array of section hashes to show as tabs
+  - *Default Tab* -- Hash of the initially selected tab
+  - *Default From Data* -- Use the data value to pick the default
+- **Tab Group Selector** -- Controls which groups display as tabs. Same properties as above but for groups.
+
+### Advanced
+
+- **Templated** -- Custom template-driven rendering. The *Template* property holds the template string.
+- **Templated Entity Lookup** -- Template-driven entity search and selection with a *Template* property.
+
+When an InputType has additional properties, they appear in a dedicated section of the Input tab after the standard fields.
+
+## Reordering and Moving Inputs
+
+- Use the left and right arrow buttons in the properties panel to move an input within its row.
+- Rows can be moved up or down using arrow buttons on the row header.
+- When drag-and-drop is enabled, inputs can be dragged within rows or across rows, and rows can be dragged within groups or across groups.
+
+## Next Steps
+
+- Learn about [Solvers](Solvers.md) to add computed values
+- Manage option lists for selection inputs in the Options tab (see [Getting Started](Getting-Started.md))
+- Return to the [Table of Contents](ToC.md)

package/user-documentation/Sections.md

@@ -0,0 +1,36 @@
+# Sections
+
+Sections are the top-level building blocks of a form. Every form has at least one section, and each section contains one or more groups of inputs.
+
+## Creating a Section
+
+Click the **Add Section** button in the visual editor toolbar. A new section is created with an auto-generated name and hash (e.g. "Section 2" with hash "S2"). The new section includes one empty group by default.
+
+## Section Properties
+
+Select a section by clicking its header in the visual editor or choosing it from the Section tab in the properties panel. The following properties are available:
+
+- **Name** -- The display label for the section (e.g. "Personal Information"). Click the name in the visual editor to edit it inline.
+- **Hash** -- A unique identifier used in the manifest data structure (e.g. "S1", "PersonalInfo"). Click the hash in the visual editor to edit it inline.
+- **Description** -- A multi-line description of the section's purpose.
+- **CSSClass** -- A CSS class name applied to the section container for custom styling.
+- **CustomCSS** -- Raw CSS rules scoped to the section (e.g. `h3 { color: red; }`).
+
+## Reordering Sections
+
+Sections can be moved up or down using the arrow buttons on the section header in the visual editor. When drag-and-drop is enabled, you can also drag sections to reorder them.
+
+## Deleting a Section
+
+Click the delete button on the section header. This removes the section and all of its groups, rows, and inputs.
+
+## Section Solvers
+
+Each section can have solver expressions attached to it. These are evaluated when the form renders and can compute values, show/hide elements, or set defaults. Solvers are managed from the section properties in the properties panel, where you can add, edit, reorder, and remove them.
+
+See [Solvers](Solvers.md) for details on how solver expressions work.
+
+## Next Steps
+
+- Learn about [Groups](Groups.md) to organize inputs within sections
+- Return to the [Table of Contents](ToC.md)

package/user-documentation/Shortcuts.md

@@ -0,0 +1,44 @@
+# Keyboard Shortcuts
+
+The form editor supports keyboard shortcuts for common editing tasks. These work in the visual editor and properties panel.
+
+## Inline Editing
+
+When editing a name, hash, or layout value inline in the visual editor:
+
+- **Enter** -- Confirm the edit and save the value
+- **Escape** -- Cancel the edit and revert to the original value
+
+## Input Type Picker
+
+When the input type picker is open:
+
+- **Escape** -- Close the picker without making a selection
+- Type in the search box to filter input types by name
+
+## Searchable Selectors
+
+The Group tab and other searchable dropdowns support keyboard navigation:
+
+- **Escape** -- Close the dropdown
+- Type to filter the list of items
+
+## Solver Editor
+
+When working in the solver code editor:
+
+- The code editor supports standard text editing shortcuts (select all, copy, paste, undo, redo)
+- Click **Insert** next to any input in the reference list to paste its address at the cursor
+
+## General Tips
+
+- Click any editable label in the visual editor to begin inline editing
+- Click a section, group, or input to select it and show its properties
+- Use the properties panel tabs to switch between Form, Section, Group, Input, Options, and Help views
+- The tab bar shows a menu button when there are more tabs than can fit; click it to see hidden tabs
+
+## Next Steps
+
+- Learn about [Solvers](Solvers.md) for computed values
+- Review [Getting Started](Getting-Started.md) for an overview
+- Return to the [Table of Contents](ToC.md)

package/user-documentation/Solver-Expression-Walkthrough.md

@@ -0,0 +1,176 @@
+# Solver Expression Walkthrough
+
+This guide walks through the basics of writing solver expressions step by step. By the end, you will understand how to create computed values, reference form inputs, and use functions.
+
+## What is a Solver Expression?
+
+A solver expression is a formula that the form engine evaluates at runtime. It can compute values, look up data, compare conditions, and assign results to form fields. Expressions are attached to sections (or to Tabular/RecordSet groups) and run automatically when the form renders or when data changes.
+
+## Your First Expression
+
+The simplest expression assigns a constant value:
+
+```
+DefaultRate = 0.05
+```
+
+This creates a variable called `DefaultRate` with the value `0.05`. The left side of the `=` is the assignment target and the right side is the value.
+
+## Referencing Inputs
+
+Solver expressions can reference any input in the form by its hash. If your form has inputs with hashes `Price` and `Quantity`, you can compute a total:
+
+```
+Total = Price * Quantity
+```
+
+When the form renders, the solver reads the current values of `Price` and `Quantity`, multiplies them, and writes the result to `Total`. If `Total` is also an input in the form, it will display the computed value.
+
+## Arithmetic Operators
+
+Expressions support standard arithmetic with the following operators, listed from highest to lowest precedence:
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `^` | Exponentiation | `2 ^ 3` gives `8` |
+| `*` | Multiplication | `5 * 3` gives `15` |
+| `/` | Division | `15 / 3` gives `5` |
+| `%` | Modulus | `7 % 3` gives `1` |
+| `+` | Addition | `5 + 3` gives `8` |
+| `-` | Subtraction | `5 - 3` gives `2` |
+
+Parentheses override precedence:
+
+```
+Result = (Price + Tax) * Quantity
+```
+
+## Using Functions
+
+Functions are called by name with arguments in parentheses. For example, to round a result to two decimal places:
+
+```
+RoundedTotal = round(Price * Quantity, 2)
+```
+
+Functions are case-insensitive. `ROUND`, `Round`, and `round` all work the same way.
+
+See [Solver Functions](Solver-Functions.md) for the complete list of available functions.
+
+## String Values
+
+Use double quotes for string literals:
+
+```
+Status = if(Total, ">", 1000, "High Value", "Standard")
+```
+
+String values can contain special characters. Use `,` for commas inside function arguments (since commas normally separate arguments):
+
+```
+Label = join(", ", FirstName, LastName)
+```
+
+The `resolvehtmlentities` function can convert HTML entities to their actual characters when needed.
+
+## Conditional Logic
+
+### The if Function
+
+The `if` function compares two values and returns one of two results:
+
+```
+if(left, operator, right, trueValue, falseValue)
+```
+
+Operators include `<`, `>`, `<=`, `>=`, `==` (loose equality), and `===` (strict equality). You can also use `LT`, `GT`, `LTE`, `GTE` as aliases.
+
+```
+Discount = if(Total, ">=", 100, Total * 0.1, 0)
+```
+
+Nested conditions handle multiple outcomes:
+
+```
+Grade = if(Score, ">=", 90, "A", if(Score, ">=", 80, "B", if(Score, ">=", 70, "C", "F")))
+```
+
+### The when Function
+
+The `when` function is a simpler check for whether a value is truthy (exists and is not empty):
+
+```
+DisplayName = when(Nickname, Nickname, FullName)
+```
+
+If `Nickname` has a value, use it; otherwise fall back to `FullName`.
+
+## Reading Application State
+
+Use `getvalue` to access data from anywhere in the application state:
+
+```
+TaxRate = getvalue("AppData.Settings.TaxRate")
+```
+
+The path must be a quoted string. Array elements use bracket notation:
+
+```
+FirstItem = getvalue("AppData.Cart.Items[0].Name")
+```
+
+## Aggregate Functions
+
+When working with arrays of data, aggregate functions compute summaries:
+
+```
+TotalCost = sum(ItemPrices)
+AverageCost = mean(ItemPrices)
+ItemCount = count(ItemPrices)
+HighestPrice = max(ItemPrices)
+LowestPrice = min(ItemPrices)
+```
+
+These work on arrays. You can use `flatten` to gather values from nested data structures:
+
+```
+AllPopulations = flatten(getvalue("AppData.Cities[].population"))
+TotalPopulation = sum(AllPopulations)
+```
+
+## Null Coalescence Assignment
+
+Use `?=` instead of `=` to only assign a value if the target is currently empty or undefined:
+
+```
+DefaultName ?= "Unnamed"
+```
+
+This sets `DefaultName` to `"Unnamed"` only if it does not already have a value. This is useful for setting initial defaults without overwriting user input.
+
+## Putting It All Together
+
+Here is a realistic example that computes a shopping cart summary:
+
+```
+Subtotal = sum(flatten(getvalue("AppData.Cart.Items[].Price")))
+TaxRate = getvalue("AppData.Settings.TaxRate")
+Tax = round(Subtotal * TaxRate, 2)
+Total = Subtotal + Tax
+DiscountApplied = if(Total, ">=", 100, "Yes", "No")
+FinalTotal = if(DiscountApplied, "==", "Yes", round(Total * 0.9, 2), Total)
+```
+
+Each expression references the results of previous ones. The ordinal system (all default to 1 here) ensures they execute in order.
+
+## Execution Order and Ordinals
+
+Solvers execute in ordinal order. All solvers with ordinal 1 run first, then ordinal 2, and so on. Within the same ordinal, solvers execute in the order they appear in the manifest.
+
+Most solvers use the default ordinal of 1. When you need a solver to run after others have completed, give it a higher ordinal (2, 3, etc.). This is useful when one group of calculations depends on the results of another.
+
+## Next Steps
+
+- Read [Solver Expressions Advanced Topics](Solver-Expressions-Advanced.md) for scope rules, set operations, and tabular solvers
+- Browse the [Solver Functions](Solver-Functions.md) reference for the complete function list
+- Return to the [Table of Contents](ToC.md)