@{
    ViewData["Title"] = "Custom Formula Item Templates - Help";
}

<div class="row g-4">
    <div class="col-lg-9">
        <nav aria-label="breadcrumb" class="mb-3">
            <ol class="breadcrumb">
                <li class="breadcrumb-item"><a asp-controller="Help" asp-action="Index">Help Center</a></li>
                <li class="breadcrumb-item active">Custom Formula Item Templates</li>
            </ol>
        </nav>

        <h1 class="h3 mb-1"><i class="bi bi-calculator text-info me-2"></i>Custom Formula Item Templates</h1>
        <p class="text-muted mb-4">Build reusable pricing formulas for complex fabricated items.</p>

        <div class="card border-0 shadow-sm mb-4">
            <div class="card-body">
                <h2 class="h5">What are formula templates?</h2>
                <p>
                    Some items &mdash; roof curbs, electrical enclosures, welded frames &mdash; have prices that depend on
                    exact measurements rather than estimated surface area. Custom Formula Item Templates let you define a
                    reusable NCalc expression that automatically calculates the price (or surface area) once a user enters
                    the measurements.
                </p>
                <p>
                    Templates are created once in <strong>Company Settings &rarr; Custom Formulas</strong> and then
                    appear as a selectable item type in the quote and job item wizards.
                </p>
            </div>
        </div>

        <div class="card border-0 shadow-sm mb-4">
            <div class="card-body">
                <h2 class="h5">Output modes</h2>
                <div class="table-responsive">
                    <table class="table table-sm">
                        <thead class="table-light">
                            <tr><th>Mode</th><th>Formula output</th><th>How it&rsquo;s priced</th></tr>
                        </thead>
                        <tbody>
                            <tr>
                                <td><strong>Fixed Rate</strong></td>
                                <td>A dollar amount</td>
                                <td>Stored as <code>ManualUnitPrice</code>; multiplied by quantity for the line total.</td>
                            </tr>
                            <tr>
                                <td><strong>Surface Area</strong></td>
                                <td>Square footage</td>
                                <td>Passed to the standard coating engine; priced per your operating cost rates.</td>
                            </tr>
                        </tbody>
                    </table>
                </div>
            </div>
        </div>

        <div class="card border-0 shadow-sm mb-4">
            <div class="card-body">
                <h2 class="h5">Creating a template</h2>
                <ol>
                    <li>Go to <strong>Company Settings &rarr; Custom Formulas</strong> and click <strong>New Template</strong>.</li>
                    <li>Enter a name and choose the output mode.</li>
                    <li>Add the measurement <strong>fields</strong> users will fill in (e.g. <code>length_in</code>, <code>width_in</code>).</li>
                    <li>Write the <strong>formula</strong> using those field names. Example for a box surface area in inches:
                        <pre class="bg-light p-2 rounded mt-1 mb-0">2*(length_in*width_in + length_in*height_in + width_in*height_in) / 144 * rate</pre>
                    </li>
                    <li>Click <strong>Run</strong> to test the formula with your default values.</li>
                    <li>Optionally upload a <strong>diagram image</strong> &mdash; users will see it when they select this template.</li>
                    <li>Save the template.</li>
                </ol>

                <h3 class="h6 mt-3">Using AI to generate a formula</h3>
                <p>
                    In the template editor, enter a description of the item in the <strong>AI Formula Generator</strong> box
                    and optionally attach a diagram image. Claude will suggest a formula, field list, and output mode.
                    Review and adjust before saving.
                </p>
            </div>
        </div>

        <div class="card border-0 shadow-sm mb-4">
            <div class="card-body">
                <h2 class="h5">Adding a formula item to a quote or job</h2>
                <ol>
                    <li>In the item wizard, select <strong>Custom Formula Item</strong> (only visible if at least one active template exists).</li>
                    <li>Choose a template from the dropdown. The template&rsquo;s diagram will appear for reference.</li>
                    <li>Enter the measurements and click <strong>Calculate</strong> to preview the result.</li>
                    <li>Adjust the description and quantity, then continue to the coatings and prep steps.</li>
                </ol>
            </div>
        </div>

        <div class="card border-0 shadow-sm mb-4">
            <div class="card-body">
                <h2 class="h5">Common formula patterns</h2>
                <p>These ready-to-use templates cover the most common fabricated item shapes. Copy the fields and formula exactly, then adjust the Default Rate for your shop.</p>

                <h3 class="h6 mt-3 mb-2"><i class="bi bi-box me-1"></i>6-Sided Box (roof curbs, enclosures)</h3>
                <p class="text-muted small mb-2">Calculates the total outer surface area of all six faces.</p>
                <div class="table-responsive mb-2">
                    <table class="table table-sm table-bordered">
                        <thead class="table-light"><tr><th>Variable name</th><th>Label</th><th>Default</th></tr></thead>
                        <tbody>
                            <tr><td><code>l_in</code></td><td>Length (inches)</td><td>24</td></tr>
                            <tr><td><code>w_in</code></td><td>Width (inches)</td><td>24</td></tr>
                            <tr><td><code>h_in</code></td><td>Height (inches)</td><td>12</td></tr>
                        </tbody>
                    </table>
                </div>
                <pre class="bg-light p-2 rounded mb-1">2*(l_in*w_in + l_in*h_in + w_in*h_in) / 144 * rate</pre>
                <p class="text-muted small mb-3">Output mode: <strong>Fixed Rate</strong> &mdash; suggested rate: your $/sqft coating price. A 24&times;24&times;12 box at $3.50/sqft = $28.00.</p>

                <h3 class="h6 mt-3 mb-2"><i class="bi bi-circle me-1"></i>Cylinder (pipe ends, round housings)</h3>
                <p class="text-muted small mb-2">Lateral surface plus two circular end caps.</p>
                <div class="table-responsive mb-2">
                    <table class="table table-sm table-bordered">
                        <thead class="table-light"><tr><th>Variable name</th><th>Label</th><th>Default</th></tr></thead>
                        <tbody>
                            <tr><td><code>d_in</code></td><td>Diameter (inches)</td><td>12</td></tr>
                            <tr><td><code>h_in</code></td><td>Height (inches)</td><td>18</td></tr>
                        </tbody>
                    </table>
                </div>
                <pre class="bg-light p-2 rounded mb-1">(3.14159 * d_in * h_in + 2 * 3.14159 * Pow(d_in/2, 2)) / 144 * rate</pre>
                <p class="text-muted small mb-3">Output mode: <strong>Fixed Rate</strong> &mdash; a 12&Prime; diameter &times; 18&Prime; tall cylinder at $3.50/sqft &asymp; $10.21.</p>

                <h3 class="h6 mt-3 mb-2"><i class="bi bi-layout-text-window me-1"></i>Flat Panel</h3>
                <p class="text-muted small mb-2">Simple rectangular sheet &mdash; one face only.</p>
                <div class="table-responsive mb-2">
                    <table class="table table-sm table-bordered">
                        <thead class="table-light"><tr><th>Variable name</th><th>Label</th><th>Default</th></tr></thead>
                        <tbody>
                            <tr><td><code>l_in</code></td><td>Length (inches)</td><td>24</td></tr>
                            <tr><td><code>w_in</code></td><td>Width (inches)</td><td>12</td></tr>
                        </tbody>
                    </table>
                </div>
                <pre class="bg-light p-2 rounded mb-1">l_in * w_in / 144 * rate</pre>
                <p class="text-muted small mb-0">Output mode: <strong>Fixed Rate</strong> &mdash; a 24&Prime;&times;12&Prime; panel at $3.50/sqft = $7.00.</p>
            </div>
        </div>

        <div class="card border-0 shadow-sm mb-4">
            <div class="card-body">
                <h2 class="h5"><i class="bi bi-collection text-primary me-2"></i>Community Formula Library</h2>
                <p>
                    The Community Formula Library lets companies share their custom templates with the entire
                    Powder Coating Logix user base. Any company can browse published formulas, preview the
                    fields and expression, and import a copy into their own library in one click.
                </p>
                <p>
                    Access the library from <strong>Company Settings &rarr; Custom Formulas &rarr; Community Library</strong>.
                </p>

                <h3 class="h6 mt-3">Sharing a formula</h3>
                <ol>
                    <li>Open <strong>Company Settings &rarr; Custom Formulas</strong>.</li>
                    <li>Find the template you want to share. The <strong>Library</strong> column shows its current status.</li>
                    <li>Click <strong>Share</strong>. Optionally add comma-separated <strong>Tags</strong> and an <strong>Industry Hint</strong> to help others discover it.</li>
                    <li>Click <strong>Publish to Library</strong>. The template is immediately visible to all users.</li>
                </ol>
                <p class="text-muted small">
                    Only templates you created fresh, or imported templates you have since modified, are eligible to share.
                    Unmodified copies of someone else&rsquo;s formula cannot be re-published (this keeps the library from filling with duplicates).
                </p>

                <h3 class="h6 mt-3">Browsing and importing</h3>
                <ol>
                    <li>Open the library via the <strong>Community Library</strong> button on the Custom Formulas tab.</li>
                    <li>Use the search bar, <strong>Output Mode</strong> filter, or <strong>Industry</strong> field to narrow results.</li>
                    <li>Click <strong>Preview &amp; Import</strong> on any card to see the full formula, fields, and diagram before committing.</li>
                    <li>Click <strong>Import to My Formulas</strong> in the preview modal. A private copy is added to your local template library.</li>
                </ol>
                <p class="text-muted small">
                    Imported copies are fully independent &mdash; you can edit, rename, or delete them without affecting the original.
                    If the original creator removes their diagram image, the image is also cleared from your copy automatically.
                </p>

                <h3 class="h6 mt-3">Attribution &amp; &ldquo;Inspired by&rdquo;</h3>
                <p>
                    Every library card shows the <strong>source company name</strong> so credit stays with the original creator.
                    If you import a formula, modify it, and then share your version back to the community, your card will display
                    an <em>&ldquo;Inspired by &hellip;&rdquo;</em> line crediting the formula it was derived from.
                </p>

                <h3 class="h6 mt-3">Rating formulas</h3>
                <p>
                    On any formula card that was shared by another company, you&rsquo;ll see a <strong>Rate:</strong> section
                    with thumbs&nbsp;up (<i class="bi bi-hand-thumbs-up"></i>) and thumbs&nbsp;down (<i class="bi bi-hand-thumbs-down"></i>) buttons.
                    Click once to cast your vote; click the same button again to remove it.
                    Clicking the opposite button switches your vote immediately.
                </p>
                <ul class="mb-3">
                    <li class="mb-1">Votes are cast per company &mdash; each company gets one vote per formula.</li>
                    <li class="mb-1">You cannot rate your own formulas.</li>
                    <li class="mb-1">The count next to each button updates instantly without a page reload.</li>
                    <li class="mb-1">The library is sorted by net rating (thumbs up minus thumbs down), so well-rated formulas rise to the top.</li>
                </ul>

                <h3 class="h6 mt-3">Your own shared formulas</h3>
                <p>
                    Formulas your company has published appear in the library with a gold <strong>Your Formula</strong> badge.
                    Clicking <strong>Manage</strong> on your own card takes you back to Company Settings where you can edit or unshare it.
                    To remove a formula from the community library, click <strong>Unshare</strong> in the Library column &mdash;
                    it disappears from the browse page immediately, but anyone who already imported it keeps their copy.
                </p>
            </div>
        </div>

        <div class="card border-0 shadow-sm mb-4">
            <div class="card-body">
                <h2 class="h5">NCalc formula reference</h2>
                <p>Formulas use <a href="https://ncalc.github.io/ncalc/" target="_blank" rel="noopener">NCalc</a> syntax:</p>
                <ul>
                    <li>Standard operators: <code>+ - * / % Pow(b, e)</code></li>
                    <li>Functions: <code>Abs(x) Round(x, d) Max(a, b) Min(a, b) Sqrt(x)</code></li>
                    <li>Variable names must start with a letter and contain only letters, digits, or underscores.</li>
                    <li>The reserved variable <code>rate</code> is pre-populated from the template&rsquo;s Default Rate.</li>
                </ul>
            </div>
        </div>
    </div>

    <div class="col-lg-3 d-none d-lg-block">
        @await Html.PartialAsync("_HelpNav")
    </div>
</div>
