Calculator Action

• Why this package?
• Installation
• Two action classes
• Basic Usage — Table Action
• Page Header Action
• Multiply & Divide Example — Quote Builder
• Another Example — Payroll Calculator
• CalcField API
• CalculatorAction / CalculatorPageAction API
• How it Works
  • Negative total warning
  • Flash animation
• Server-Side Safety
• License

A plug-and-play real-time calculator action for Filament v3 & v4 — instant client-side arithmetic with zero Livewire round-trips.

Works in both table row actions (CalculatorAction) and page header actions (CalculatorPageAction).

#Why this package?

Using ->live() on Filament form fields triggers a Livewire server round-trip on every keystroke. For a simple numeric calculator (subtotal + fees − discount = total), that's a server call every time the user types a digit — sluggish and unnecessary.

This package generates lightweight inline JavaScript (onkeyup / onchange) that performs all arithmetic directly in the browser. No server call. No debounce. No waiting. The result field updates the instant a key is released.

Server-side recomputation via computeResult() is still performed inside ->action() to ensure the stored value is always trustworthy.

#Installation

composer require osama-dev/filament-calculator-action

No extra configuration needed — the service provider is auto-discovered.

#Two action classes

Both share the exact same API via the HasCalculation trait.

#Basic Usage — Table Action

use OsamaDev\FilamentCalculatorAction\CalculatorAction;
use OsamaDev\FilamentCalculatorAction\CalcField;
use Filament\Forms\Components\Section;
use Filament\Forms\Components\Textarea;
use Filament\Forms\Components\TextInput;

CalculatorAction::make('issue_receipt')
    ->label('Mark Fulfilled & Issue Receipt')
    ->icon('heroicon-o-document-text')
    ->color('success')
    ->visible(fn ($record): bool => $record->status === 'in_progress')
    ->calcSectionHeading('Receipt Details')
    ->calcColumns(2)
    ->calcPrefix('EGP')
    ->calcFields([
        CalcField::make('subtotal')
            ->label('Subtotal')
            ->adds()
            ->required()
            ->helperText('including taxes')
            ->default(fn ($record) => (float) ($record->sub_total ?? 0))
            ->columnSpan(1),
        CalcField::make('extra_fees')
            ->label('Extra Fees')
            ->adds()
            ->default(0)
            ->columnSpan(1),
        CalcField::make('discount')
            ->label('Discount')
            ->subtracts()
            ->default(0)
            ->columnSpan(1),
        CalcField::make('total')
            ->label('Total')
            ->result(),
    ])
    ->form([
        Section::make('Booking Context')
            ->schema([
                TextInput::make('user_name')
                    ->label('User')
                    ->default(fn ($record) => $record->user?->full_name ?? 'Deleted User')
                    ->disabled(),
                TextInput::make('reference')
                    ->label('Reference')
                    ->default(fn ($record) => $record->reference)
                    ->disabled(),
            ])->columns(2),
        Textarea::make('notes')
            ->label('Notes')
            ->rows(3)
            ->columnSpanFull(),
    ])
    ->action(function (array $data, $record) {
        $subtotal = (float) ($data['subtotal'] ?? 0);
        $discount = (float) ($data['discount'] ?? 0);
        $extraFees = (float) ($data['extra_fees'] ?? 0);
        $total = $subtotal - $discount + $extraFees;

        // Or use the helper: $total = $this->computeResult($data);

        $record->invoice()->create([
            'subtotal'   => $subtotal,
            'discount'   => $discount,
            'extra_fees' => $extraFees,
            'total'      => $total,
            'notes'      => $data['notes'] ?? null,
        ]);
    })
    ->modalHeading('Issue Receipt')
    ->modalSubmitActionLabel('Create Receipt')

Note: ->form([...]) (v3) or ->schema([...]) (v4) defines your custom fields. The calculator section is always appended after your form fields automatically. Both methods work in both versions.

#Page Header Action

Use CalculatorPageAction when placing the action in getHeaderActions() on a resource page (View, Edit, etc.):

use OsamaDev\FilamentCalculatorAction\CalculatorPageAction;
use OsamaDev\FilamentCalculatorAction\CalcField;

protected function getHeaderActions(): array
{
    return [
        CalculatorPageAction::make('issue_receipt')
            ->label('Mark Fulfilled & Issue Receipt')
            ->icon('heroicon-o-document-text')
            ->color('success')
            ->visible(fn ($record): bool => $record->status === 'in_progress')
            ->calcSectionHeading('Receipt Details')
            ->calcPrefix('EGP')
            ->calcColumns(2)
            ->calcFields([
                CalcField::make('subtotal')->label('Subtotal')->adds()->required()->default(fn ($record) => (float) ($record->sub_total ?? 0))->columnSpan(1),
                CalcField::make('extra_fees')->label('Extra Fees')->adds()->default(0)->columnSpan(1),
                CalcField::make('discount')->label('Discount')->subtracts()->default(0)->columnSpan(1),
                CalcField::make('total')->label('Total')->result(),
            ])
            ->action(function (array $data, $record) {
                $total = $this->computeResult($data);
                // persist invoice...
            }),
    ];
}

#Multiply & Divide Example — Quote Builder

CalculatorAction::make('generate_quote')
    ->label('Generate Quote')
    ->calcSectionHeading('Quote Breakdown')
    ->calcColumns(2)
    ->calcPrefix('EGP')
    ->calcFields([
        CalcField::make('unit_price')
            ->label('Unit Price')
            ->adds()
            ->required()
            ->columnSpan(1),
        CalcField::make('quantity')
            ->label('Quantity')
            ->multiplies()
            ->default(1)
            ->columnSpan(1),
        CalcField::make('discount')
            ->label('Discount')
            ->subtracts()
            ->default(0)
            ->columnSpan(1),
        CalcField::make('total')
            ->label('Total')
            ->result(),
    ])
    ->action(function (array $data, $record) {
        $total = $this->computeResult($data);
        // formula: (unit_price - discount) * quantity
    })

Order of operations: adds and subtracts are applied first, then multiplies, then divides. So (unit_price - discount) * quantity / installments works as expected.

#Another Example — Payroll Calculator

CalculatorAction::make('process_payroll')
    ->label('Process Payroll')
    ->calcSectionHeading('Payroll Breakdown')
    ->calcColumns(2)
    ->calcPrefix('USD')
    ->calcFields([
        CalcField::make('base_salary')
            ->label('Base Salary')
            ->adds()
            ->required()
            ->default(5000)
            ->columnSpan(1),
        CalcField::make('bonus')
            ->label('Bonus')
            ->adds()
            ->default(0)
            ->columnSpan(1),
        CalcField::make('deductions')
            ->label('Deductions')
            ->subtracts()
            ->default(0)
            ->columnSpan(1),
        CalcField::make('tax_withholding')
            ->label('Tax Withholding')
            ->subtracts()
            ->default(0)
            ->columnSpan(1),
        CalcField::make('net_salary')
            ->label('Net Salary')
            ->result(),
    ])
    ->action(function (array $data, $record) {
        $net = $this->computeResult($data);

        $record->payroll()->create([
            'base_salary'     => $data['base_salary'],
            'bonus'           => $data['bonus'],
            'deductions'      => $data['deductions'],
            'tax_withholding' => $data['tax_withholding'],
            'net_salary'      => $net,
        ]);
    })

#CalcField API

#CalculatorAction / CalculatorPageAction API

#How it Works

Each non-result CalcField gets two HTML event attributes: onkeyup and onchange. Both run the same small inline script that reads all field values via document.querySelector('[data-calc-field="name"]'), computes the result, and updates the result field:

// Generated JS (simplified)
var __r = ((unit_price) - (discount)) * (quantity);
var __t = document.querySelector('[data-calc-field="total"]');
if (__t) {
    __t.value = __r.toFixed(2);

    // Negative warning — red outline + red text
    if (__r < 0) {
        __t.style.color = '#dc2626';
        __t.style.outline = '2px solid #dc2626';
    } else {
        __t.style.color = '';
        __t.style.outline = '';
    }

    // Flash animation — yellow highlight fades out
    clearTimeout(window.__ct);
    __t.style.transition = 'background-color 0.4s';
    __t.style.backgroundColor = '#fef9c3';
    window.__ct = setTimeout(function () { __t.style.backgroundColor = ''; }, 400);
}

No framework dependency, no reactivity system, no round-trips. The result field is readOnly with dehydrated(false), so Livewire does not include it in submitted form data.

#Negative total warning

When the computed result goes below zero, the result field turns red (color + outline) to signal the user to fix the inputs before submitting. The raw negative value is shown so the user understands what's wrong.

#Flash animation

Every time a value changes and a new result is computed, the result field briefly flashes yellow then fades back — giving clear visual feedback that the calculation fired.

The flash is enabled by default and fully customisable:

->calcFlash(false)                  // disable entirely
->calcFlashColor('#d1fae5')         // change to green
->calcFlashDuration(600)            // slow it down to 600ms

#Server-Side Safety

Always recompute the total server-side inside ->action() — never trust $data['total'].

Because the result field is dehydrated(false), $data['total'] will not be present in $data. Use the computeResult() helper or compute manually from the individual field values:

->action(function (array $data) {
    // Option A — helper method
    $total = $this->computeResult($data);

    // Option B — manual (same result)
    $total = (float) ($data['subtotal'] ?? 0)
           + (float) ($data['extra_fees'] ?? 0)
           - (float) ($data['discount'] ?? 0);
})

Both options apply max(0, ...) clamping, preventing negative totals.

#License

MIT — see LICENSE.md