spouliot/PowderCoatingLogix
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add formula template walkthrough and UX improvements

Browse Source 
- 7-step guided walkthrough modal (concept, output modes, fields, formula,
  testing, box example, cylinder example); auto-shown first time the tab
  opens with no templates; always accessible via "How it works" button
- Variable pill badges below formula input showing all valid field names + rate;
  update live as fields are added/renamed; clickable to insert at cursor
- Fix: Add Field no longer shows validation error on blank new rows; validation
  only fires once the user has typed something
- Help article: added Common Formula Patterns section with box, cylinder, and
  flat panel worked examples (fields table + formula + expected output)
- HelpKnowledgeBase updated with pattern examples and walkthrough note

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Scott Pouliot
2026-05-24 11:40:54 -04:00
parent 4650ba3d4d
commit d28e639d1b
4 changed files with 415 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/PowderCoating.Web/wwwroot/js/company-settings-custom-formulas.js
+310 -3
View File
@@ -139,7 +139,7 @@
window.cfUpdateField = function (i, key, val, isNumber) {
cfFields[i][key] = isNumber ? (parseFloat(val) || 0) : val;
if (key === 'name') cfValidateFieldNameInput(i, val);
if (key === 'name') { cfValidateFieldNameInput(i, val); cfRenderVariablePills(); }
};
function cfValidateFieldName(name) {
@@ -174,13 +174,14 @@
el.innerHTML = '<p class="text-muted small">No fields yet.</p>';
return;
}
cfRenderVariablePills();
el.innerHTML = cfFields.map((f, i) => `
<div class="border rounded p-2 mb-2 bg-light">
<div class="row g-2 align-items-center">
<div class="col-3">
<input type="text" class="form-control form-control-sm font-monospace field-name-input${cfValidateFieldName(f.name) ? ' is-invalid' : ''}"
<input type="text" class="form-control form-control-sm font-monospace field-name-input${f.name && cfValidateFieldName(f.name) ? ' is-invalid' : ''}"
placeholder="var_name" value="${escHtml(f.name)}"
oninput="cfUpdateField(${i},'name',this.value)" />${cfValidateFieldName(f.name) ? `<div class="invalid-feedback">${escHtml(cfValidateFieldName(f.name))}</div>` : ''}
oninput="cfUpdateField(${i},'name',this.value)" />${f.name && cfValidateFieldName(f.name) ? `<div class="invalid-feedback">${escHtml(cfValidateFieldName(f.name))}</div>` : ''}
</div>
<div class="col-3">
<input type="text" class="form-control form-control-sm"
@@ -206,6 +207,32 @@
</div>`).join('');
}
function cfRenderVariablePills() {
const container = document.getElementById('cfVariablePills');
if (!container) return;
const names = cfFields.map(f => f.name).filter(n => n && !cfValidateFieldName(n));
const all = [...names, 'rate'];
container.innerHTML = all.map(n =>
`<span class="badge bg-secondary me-1 mb-1" style="cursor:pointer; font-size:.75rem;"
title="Click to insert into formula" onclick="cfInsertVariable('${escHtml(n)}')">${escHtml(n)}</span>`
).join('');
}
window.cfInsertVariable = function (name) {
const input = document.getElementById('cfFormula');
if (!input) return;
const start = input.selectionStart ?? input.value.length;
const end = input.selectionEnd ?? input.value.length;
const before = input.value.slice(0, start);
const after = input.value.slice(end);
const needsSpace = before.length > 0 && !/[\s(+\-*/]$/.test(before);
const insert = (needsSpace ? ' ' : '') + name;
input.value = before + insert + after;
const cursor = start + insert.length;
input.setSelectionRange(cursor, cursor);
input.focus();
};
// ── Formula Test ──────────────────────────────────────────────────────────
window.cfTestFormula = async function () {
@@ -421,4 +448,284 @@
function getAntiForgeryToken() {
return document.querySelector('input[name="__RequestVerificationToken"]')?.value ?? '';
}
// ── Walkthrough ───────────────────────────────────────────────────────────
let cfWtStep = 0;
const cfWtSteps = [
{
title: 'What are Formula Templates?',
icon: 'bi-lightbulb text-warning',
html: `
<p>Some items &mdash; roof curbs, electrical enclosures, welded frames &mdash; have prices that depend on
<strong>exact measurements</strong> rather than estimated surface area.</p>
<p>A <strong>Formula Template</strong> lets you define a reusable calculation once in Company Settings.
When a staff member adds that item to a quote or job, they just fill in the measurements and the price
calculates automatically &mdash; no mental math, no spreadsheets.</p>
<div class="alert alert-info mb-0">
<i class="bi bi-info-circle me-2"></i>
Templates appear as a <strong>"Custom Formula Item"</strong> option in the quote and job item wizard,
but only when at least one active template exists.
</div>`
},
{
title: 'Output Modes',
icon: 'bi-toggle2-on text-primary',
html: `
<p>When you create a template, you choose how the formula result is used:</p>
<div class="table-responsive">
<table class="table table-bordered table-sm mb-3">
<thead class="table-light">
<tr><th style="width:30%">Mode</th><th>Formula produces&hellip;</th><th>How it&rsquo;s priced</th></tr>
</thead>
<tbody>
<tr>
<td><span class="badge bg-primary">Fixed Rate</span></td>
<td>A <strong>dollar amount</strong></td>
<td>Used directly as the item&rsquo;s unit price. Best for items priced by a custom rate (e.g. $/sqft of surface).</td>
</tr>
<tr>
<td><span class="badge bg-success">Surface Area</span></td>
<td><strong>Square footage</strong></td>
<td>Fed into the standard coating engine and priced using your operating cost rates &mdash; just like any other coated item.</td>
</tr>
</tbody>
</table>
</div>
<div class="alert alert-secondary mb-0">
<i class="bi bi-star me-1"></i>
<strong>Most shops start with Fixed Rate.</strong> It gives you full control over the per-unit price
and is the easiest to reason about.
</div>`
},
{
title: 'Step 1 &mdash; Define Your Fields',
icon: 'bi-input-cursor-text text-success',
html: `
<p>Fields are the <strong>measurements your staff will fill in</strong> when they use the template.
Each field becomes an input box in the item wizard.</p>
<div class="row g-3 mb-3">
<div class="col-md-6">
<div class="card border-success h-100">
<div class="card-header bg-success text-white py-1 small fw-semibold">What you set up</div>
<div class="card-body py-2 small">
<table class="table table-sm mb-0">
<tr><th>Variable name</th><td><code>length_in</code></td></tr>
<tr><th>Label</th><td>Length (inches)</td></tr>
<tr><th>Default</th><td>24</td></tr>
</table>
<table class="table table-sm mb-0 mt-2">
<tr><th>Variable name</th><td><code>width_in</code></td></tr>
<tr><th>Label</th><td>Width (inches)</td></tr>
<tr><th>Default</th><td>12</td></tr>
</table>
</div>
</div>
</div>
<div class="col-md-6">
<div class="card border-primary h-100">
<div class="card-header bg-primary text-white py-1 small fw-semibold">What staff sees in the wizard</div>
<div class="card-body py-2">
<label class="form-label small mb-1">Length (inches)</label>
<input type="number" class="form-control form-control-sm mb-2" value="24" readonly>
<label class="form-label small mb-1">Width (inches)</label>
<input type="number" class="form-control form-control-sm" value="12" readonly>
</div>
</div>
</div>
</div>
<div class="alert alert-warning mb-0 small">
<i class="bi bi-exclamation-triangle me-1"></i>
Variable names must <strong>start with a letter</strong> and contain only letters, digits, or underscores &mdash; no spaces.
Good: <code>length_in</code> &nbsp; Bad: <code>length in</code> or <code>1length</code>
</div>`
},
{
title: 'Step 2 &mdash; Write the Formula',
icon: 'bi-braces text-info',
html: `
<p>The formula is a math expression using your <strong>field variable names</strong> plus the reserved
variable <code>rate</code> (pre-filled from the template&rsquo;s Default Rate).</p>
<p class="fw-semibold mb-1">Example &mdash; flat panel price (inches &rarr; sqft &rarr; dollars):</p>
<pre class="bg-light border rounded p-3 mb-3" style="font-size:.9rem">length_in * width_in / 144 * rate</pre>
<p class="fw-semibold mb-1">Supported operations:</p>
<div class="row g-2 mb-3">
<div class="col-sm-6">
<ul class="mb-0 small">
<li><code>+ &nbsp;- &nbsp;* &nbsp;/</code> &mdash; basic math</li>
<li><code>Pow(base, exp)</code> &mdash; exponents</li>
<li><code>Sqrt(x)</code> &mdash; square root</li>
</ul>
</div>
<div class="col-sm-6">
<ul class="mb-0 small">
<li><code>Round(x, digits)</code> &mdash; rounding</li>
<li><code>Abs(x)</code> &mdash; absolute value</li>
<li><code>Max(a,b) &nbsp;Min(a,b)</code></li>
</ul>
</div>
</div>
<div class="alert alert-info mb-0 small">
<i class="bi bi-info-circle me-1"></i>
<code>rate</code> is always available &mdash; you set it as the <strong>Default Rate</strong> on the template
and staff can override it per-use. Don&rsquo;t create a field called <code>rate</code>.
</div>`
},
{
title: 'Step 3 &mdash; Test Before Saving',
icon: 'bi-play-circle text-success',
html: `
<p>Before saving, use the <strong>Run</strong> button to verify your formula evaluates correctly
using each field&rsquo;s default value.</p>
<div class="card border-success mb-3">
<div class="card-body py-2">
<div class="row g-2 align-items-end">
<div class="col">
<label class="form-label small mb-1 fw-semibold">Formula</label>
<input type="text" class="form-control form-control-sm font-monospace" value="length_in * width_in / 144 * rate" readonly>
</div>
<div class="col-auto">
<button class="btn btn-success btn-sm" disabled><i class="bi bi-play-fill me-1"></i>Run</button>
</div>
<div class="col-auto">
<span class="fw-bold text-success">&nbsp;= 7.0000</span>
</div>
</div>
<div class="text-muted small mt-1">Using defaults: length_in=24, width_in=12, rate=3.50 &rarr; 24&times;12/144&times;3.50 = $7.00</div>
</div>
</div>
<p class="mb-0">If the formula has an error (typo, missing variable, bad syntax) the result will
show in red with a description of the problem. Fix it before saving.</p>`
},
{
title: 'Example &mdash; 6-Sided Box',
icon: 'bi-box text-secondary',
html: `
<p>A roof curb or electrical enclosure can be priced by calculating its outer surface area.</p>
<div class="card border mb-3">
<div class="card-header py-2 fw-semibold small">Template Setup</div>
<div class="card-body py-2 small">
<div class="row g-3">
<div class="col-md-5">
<strong>Fields</strong>
<table class="table table-sm mb-0 mt-1">
<thead class="table-light"><tr><th>Variable</th><th>Label</th><th>Default</th></tr></thead>
<tbody>
<tr><td><code>l_in</code></td><td>Length (in)</td><td>24</td></tr>
<tr><td><code>w_in</code></td><td>Width (in)</td><td>24</td></tr>
<tr><td><code>h_in</code></td><td>Height (in)</td><td>12</td></tr>
</tbody>
</table>
</div>
<div class="col-md-7">
<strong>Formula</strong> <span class="text-muted">(Fixed Rate, rate = 3.50)</span>
<pre class="bg-light border rounded p-2 mt-1 mb-2" style="font-size:.8rem">2*(l_in*w_in + l_in*h_in + w_in*h_in) / 144 * rate</pre>
<strong>What it does:</strong> Calculates total outer surface area of all 6 faces
in square inches, converts to square feet (&divide;144), multiplies by rate.
<div class="mt-2 text-success fw-semibold">24&times;24&times;12 box at $3.50/sqft &rarr; $28.00</div>
</div>
</div>
</div>
</div>
<p class="mb-0 text-muted small">
<i class="bi bi-lightbulb me-1"></i>
You can add a diagram image to the template &mdash; staff will see it in the wizard as a reference
while entering measurements.
</p>`
},
{
title: 'Example &mdash; Cylinder',
icon: 'bi-vinyl text-secondary',
html: `
<p>Round parts like pipe ends or cylindrical housings use a slightly different formula.</p>
<div class="card border mb-3">
<div class="card-header py-2 fw-semibold small">Template Setup</div>
<div class="card-body py-2 small">
<div class="row g-3">
<div class="col-md-5">
<strong>Fields</strong>
<table class="table table-sm mb-0 mt-1">
<thead class="table-light"><tr><th>Variable</th><th>Label</th><th>Default</th></tr></thead>
<tbody>
<tr><td><code>d_in</code></td><td>Diameter (in)</td><td>12</td></tr>
<tr><td><code>h_in</code></td><td>Height (in)</td><td>18</td></tr>
</tbody>
</table>
</div>
<div class="col-md-7">
<strong>Formula</strong> <span class="text-muted">(Fixed Rate, rate = 3.50)</span>
<pre class="bg-light border rounded p-2 mt-1 mb-2" style="font-size:.75rem">(3.14159 * d_in * h_in + 2 * 3.14159 * Pow(d_in/2, 2)) / 144 * rate</pre>
<strong>What it does:</strong> Lateral surface area (circumference &times; height)
plus two circular end caps, converted to sqft, multiplied by rate.
<div class="mt-2 text-success fw-semibold">12&Prime; dia &times; 18&Prime; tall at $3.50/sqft &rarr; ~$10.21</div>
</div>
</div>
</div>
</div>
<div class="alert alert-success mb-0">
<i class="bi bi-check-circle me-2"></i>
<strong>You&rsquo;re ready to create your first template!</strong>
Click <strong>Get Started</strong> below to open the template editor, or close this guide
and click <strong>New Template</strong> any time.
</div>`
}
];
window.cfShowWalkthrough = function () {
cfWtStep = 0;
cfRenderWtStep();
new bootstrap.Modal(document.getElementById('cfWalkthroughModal')).show();
localStorage.setItem('cfWalkthroughSeen', '1');
};
window.cfWalkthroughNav = function (dir) {
const next = cfWtStep + dir;
if (next < 0) return;
if (next >= cfWtSteps.length) {
bootstrap.Modal.getInstance(document.getElementById('cfWalkthroughModal'))?.hide();
cfShowCreate();
return;
}
cfWtStep = next;
cfRenderWtStep();
};
function cfRenderWtStep() {
const step = cfWtSteps[cfWtStep];
const total = cfWtSteps.length;
const isLast = cfWtStep === total - 1;
// Dots
document.getElementById('cfWalkthroughDots').innerHTML = cfWtSteps.map((_, i) =>
`<span style="width:10px;height:10px;border-radius:50%;display:inline-block;cursor:pointer;
background:${i === cfWtStep ? '#0d6efd' : '#dee2e6'}"
onclick="cfWtJump(${i})" title="Step ${i+1}"></span>`
).join('');
// Content
document.getElementById('cfWalkthroughContent').innerHTML = `
<div class="d-flex align-items-center gap-2 mb-3">
<i class="bi ${step.icon} fs-4"></i>
<h6 class="mb-0 fw-semibold">${step.title}</h6>
<span class="ms-auto text-muted small">${cfWtStep + 1} of ${total}</span>
</div>
${step.html}`;
// Buttons
document.getElementById('cfWtPrevBtn').style.visibility = cfWtStep === 0 ? 'hidden' : 'visible';
const nextBtn = document.getElementById('cfWtNextBtn');
if (isLast) {
nextBtn.innerHTML = '<i class="bi bi-rocket-takeoff me-1"></i>Get Started';
nextBtn.className = 'btn btn-success';
} else {
nextBtn.innerHTML = 'Next<i class="bi bi-arrow-right ms-1"></i>';
nextBtn.className = 'btn btn-primary';
}
}
window.cfWtJump = function (i) {
cfWtStep = i;
cfRenderWtStep();
};
})();