Percentage Laravel Package

Product Decisions This Supports

• A scoped build-vs-buy call for admin UX, not platform infrastructure. The defensible framing is: this is a percentage input/display field for Laravel Nova back-office screens. It supports the decision to not spend engineering days hand-rolling a field when a percentage widget is the entire requirement — with the decision explicitly bounded to internal, staff-correctable surfaces. It is an admin UX accelerator worth roughly a day of a small ticket; it is not a platform dependency and should never appear on a strategic roadmap, gate a release, or sit on a critical path.

• Resolving what is actually being bought. The package presents two different identities: the registry metadata says "A Laravel Nova field," while its own description pitches a framework-agnostic percentage calculation helper with optional Laravel integration. Those are different products with different blast radii. The PM decision is to treat it as Nova UI only until source inspection proves otherwise, and to explicitly not assume it replaces domain-level percentage logic. That distinction is the difference between a cosmetic admin field and a silent data-integrity risk in pricing or billing.

• Unblocking low-risk internal features. Supports delivery of internal admin capabilities — discount/rate capture, completion or progress values, scoring fields, allocation percentages — inside Nova resources. These are visible, internal-only, staff-correctable surfaces where a wrong value is an annoyance and a correction, not a revenue incident.

• Enforcing an architecture boundary as a product decision. Percentage math, rounding policy, unit conventions (0–1 vs 0–100), and validation belong in the application/domain layer where they can be specified and tested. The package handles presentation and input. Making that boundary explicit early prevents the field from quietly becoming the source of truth for business rules, which is exactly the failure mode that turns a one-day admin ticket into a quarter-later data cleanup.

• Risk-scoped adoption. With 7 stars, 0 dependents, a single maintainer, and no observable production footprint, the only defensible decision it supports is a contained pilot with a priced in-house fallback — not standardization across admin surfaces, and not a bet on future upstream maintenance. No dependents means no early-warning system: when a Nova upgrade breaks it, we find out in production admin, not in CI.

• Greenlight vs. decline, stated crisply. Greenlight for internal-only Nova screens, wrapped and version-pinned. Decline for customer-facing pricing, billing, commissions, financial reporting, or anything where a silent hundred-fold unit error becomes a data-integrity or revenue incident.

When to Consider This Package

Consider it when:

• The product already runs Laravel Nova (v4/v5 compatibility confirmed, not assumed) and the need is a percentage field on one or a few admin resources.
• The requirement is genuinely thin: capture, display, or lightly format a percentage — not calculate, aggregate, localize, or chart it.
• The package's storage semantics match ours (0–100 vs 0–1, decimal precision, rounding, min/max/step) or can be reconciled through a Nova accessor/mutator without patching vendor code.
• We can pin an exact version (not ^1.0), wrap the vendor class in an internal App\Nova\Fields\InternalPercentage, and accept that we own maintenance when Nova changes.
• We can verify it cheaply: a half-day to one-day spike plus characterization tests asserting what actually lands in the database column — 0, 0.5, 12.5, 100, comma-decimal 12,5, out-of-range 150, non-numeric — not what the form displays.
• There is a clear fallback already priced: a small custom Nova field (~100 lines of PHP plus a small Vue component), or a plain number field plus server-side validation.

Look elsewhere or build in-house when:

• The product is not on Nova — the field has no reusable value outside it; use Blade/Livewire or a plain number input with validation.
• Percentage handling is core business logic — pricing, billing, commissions, compliance — or requires localization, currency-like formatting, charting, or server-enforced validation.
• The license, Nova/PHP/Laravel support matrix, tests, or asset build are unclear or unsupported. Assume no upstream responsiveness.
• The admin surface is security-sensitive and requires vendor review, an SLA, or active maintenance that a single-maintainer micro-package cannot provide.
• A plain Nova number field plus validation already satisfies the requirement with less dependency risk. At 7 stars and 0 dependents, the honest default is "build the hundred lines" unless the spike proves otherwise.

How to Pitch It (Stakeholders)

To executives: This is a small, cheap convenience for internal admin screens — a percentage input box, not a platform capability. We are piloting it on one low-traffic Nova resource with an exact version pin and a one-day engineering fallback already costed (a ~100-line custom field). Upside is roughly a day saved on an admin ticket. Downside is bounded: internal-only, staff-correctable data, no customer-facing exposure, and a documented exit. It is not on the roadmap, not a differentiator, and we will not describe it as one.

To engineering: Treat the registry metadata and the package description as describing two different products until you've read src/. If it's a Nova field, wrap it in App\Nova\Fields\InternalPercentage on day one so there's exactly one file to patch, fork, or delete. Pin the exact version. Write characterization tests around persistence before building the feature — the 0.125 vs 12.5 unit error is silent, throws nothing, and surfaces weeks later as "why is every discount showing as 0.12%?". Client-side masking is not validation; enforce with server-side ->rules() regardless of what the field claims. Test a comma-decimal locale. Add "render and persist every percentage field" to the Nova upgrade checklist, because this package almost certainly won't get a patch. If the spike shows a semantic mismatch on storage unit, validation, or locale handling, build our own field — patching a single-maintainer micro-package costs more than writing it, and removes the maintenance, upgrade, and metadata-ambiguity risk at once.

To whoever owns the admin surface after launch: You are the maintainer now. Keep the vendor call site contained, keep rounding and unit conventions in our own mutator or PercentageCalculator implementation, and do not let Percentage::of() spread through controllers and templates. A wrong percentage on an internal screen should be visibly wrong and fixable by staff — never silently wrong and exported into something a customer sees.