Nova Items Field Laravel Package

Technical Evaluation

Architecture fit

• Purpose-built Laravel Nova 5 field that persists a JSON array of scalars on an existing Eloquent model attribute. It slots into the admin layer only — no API, headless, or front-end contract is exposed, so it does not alter application domain architecture.
• Replaces free-text “comma separated” inputs and ad-hoc JSON textareas with a validated, structured editor. Good fit where the value is genuinely a short, ordered, non-relational list (tags, notification emails, checklist steps, bullet copy).
• Deliberately not a relational substitute: no normalization, no pivot table, no per-item IDs. Any requirement to filter, sort, join, or report on individual items is out of scope and should be flagged as an architectural mismatch rather than worked around.

Integration feasibility

• Single composer require bbs-lab/nova-items-field with a fluent API mirroring native Nova fields (Items::make()->chips()->suggestions()->rules()->itemRules()). Low ceremony, no service provider wiring described, no schema change beyond an existing JSON/text column.
• Dual validation surface (->rules() for the array, ->itemRules() for each row) with inline per-row errors is the strongest TPM-relevant feature: it moves data-quality enforcement into the admin UI instead of relying on downstream cleanup.
• Requires confirmation that the underlying model attribute is cast to array/json and that non-Nova write paths (imports, seeders, API endpoints, jobs) produce the same JSON shape — the field validates only what passes through Nova.

Technical risk

• PHP ^8.4 floor is the largest adoption blocker. Teams on 8.2/8.3 cannot install without a runtime upgrade; this gates the package behind an unrelated platform initiative. Verify whether the floor is a hard language-feature dependency or a policy choice.
• Laravel 13 in the support matrix implies a forward-looking or pre-release target. Confirm which combinations are GA-tested versus smoke-tested before quoting the matrix to stakeholders.
• v1.0.0 with a namespace/vendor change (blendbyte/nova-items-field → bbs-lab/nova-items-field, BBSLab\NovaItemsField\Items). The README advertises a migration table, but stored-data compatibility and method-by-method API parity must be proven, not assumed — this is a rewrite, not a patch release.
• Vendor concentration. First stable release from a small studio, itself twice-forked (dillingham → blendbyte → BBS-Lab). Public 100% PHP/JS coverage, MSI ≥ 80%, PHPStan L8, Pint/ESLint/Prettier is genuinely strong quality signalling, but quality tooling is not the same as a support commitment.
• Two overlapping constraint APIs (->rules('max:10') and ->max(10)) create ambiguity about which layer is authoritative and whether both are enforced server-side. Clarify defence-in-depth versus duplication.
• Nova licensing remains a prerequisite cost; the field inherits every Nova 5 upgrade risk (Vue component/asset pipeline churn).

Key questions

1. Is PHP 8.4 already the fleet baseline, or does adoption require a separate runtime upgrade with its own approval path?
2. Is the JSON payload byte-compatible with the blendbyte predecessor for existing records, or is a data migration/backfill required?
3. Are ->rules()/->max() enforced server-side on save, or only in the Vue layer? Can a crafted request bypass per-item validation?
4. What happens to non-string scalars (ints, booleans, nulls) in chips() and indexAsChips() views, and is there a documented canonical shape?
5. Does the package publish/version its compiled assets, and how are stale-asset issues handled after composer update?
6. Is there any published support policy, response expectation, or maintainer continuity statement?

Integration Approach

Stack fit

• Requires Laravel 11/12 (13 per matrix), Nova 5, PHP 8.4+. Clean fit for greenfield or already-upgraded Nova 5 admin panels; poor fit for estates mid-way through a Laravel 10/Nova 4 migration.
• Complements, rather than replaces, existing Nova fields — suitable for a targeted subset of resources where scalar-list editing is currently a UX and validation weak point.

Migration path

• For teams on blendbyte/nova-items-field: run the README migration table as a checklist per field, swap imports to BBSLab\NovaItemsField\Items, and diff rendered output in a staging resource before touching production forms.
• For teams on raw text/JSON columns: no data migration if the stored shape is already a flat array; if not, script a one-off normalization and validate record counts plus a sample of round-tripped edits.
• Recommend a short deprecation window: keep the legacy field class in place behind a feature flag until the new field has been exercised in production for at least one release cycle.

Compatibility

• Hard gates: PHP 8.4, Nova 5, Laravel 11+. No path for Nova 4 or Laravel 10 — verify this against the platform roadmap before committing.
• Verify coexistence with any other packages that decorate the same model attributes or override Nova form behaviour.
• Confirm i18n coverage: EN/FR ship in-box; other locales need label publishing, which is a small but real localization task with an owner.

Sequencing

1. Confirm platform prerequisites (PHP 8.4 available in CI and prod, Nova 5 in place).
2. Spike one low-risk resource (e.g. free-text tags on an internal-only model) in a feature branch.
3. Prove validation behaviour, JSON round-trip fidelity, and index/detail rendering against real data.
4. Publish the field's asset pipeline and verify cache-busting across a deploy.
5. Roll out resource-by-resource, starting with internal admin users; hold external-facing or audited resources until after the first upgrade cycle.
6. Establish a version pin (^1.0) and a defined re-evaluation point at the next minor release.

Operational Impact

Maintenance

• Low code footprint, but non-zero ownership: pin the version, subscribe to releases, and re-run the compatibility check at each Nova or Laravel minor. Nova upgrades are the dominant maintenance trigger because the field ships a Vue component tied to Nova's front-end internals.
• Budget for reviewing the vendor's release cadence in the first two quarters; a v1.0.0 package from a small studio typically churns its public API in the 1.x line.
• Keep the migration table and any local field customizations documented in-repo so a future maintainer can move off the package without archaeology.

Support

• Community/README-level support only; no SLA, no commercial backing evident. Acceptable for internal admin tooling, unacceptable for anything with a contractual uptime or audit obligation.
• Mitigation: vendor the package or maintain a maintained fork path, and ensure at least one engineer can read the Vue component and the PHP field class.
• Ensure the Nova licence and its renewal are captured in the same owner's budget as the package.

Scaling

• Data volume is bounded by the JSON column: fine for tens of items per record, poor for hundreds. ->maxHeight() and ->max() are UX/validation guards, not performance guarantees.
• No indexing on individual items — treat the field as an editing surface, never as a query surface. Reporting, search, and deduplication across records require a normalized table; plan an exit ramp if those needs appear.
• Drag-and-drop reordering and chips rendering are client-side; large lists will degrade form responsiveness before they degrade the database.

Failure modes

• Validation bypass — writes via API, imports, or seeders that skip Nova can persist malformed arrays. Add model-level or request-level validation as the authoritative guard.
• Stale assets — after an upgrade, cached JS can produce a broken or invisible field. Include asset-publish/clear in the deploy runbook.
• Malformed legacy JSON — pre-existing non-array values can break the field's hydration and produce blank forms. Run a pre-flight data audit before rollout.
• Ordering ambiguity — drag-to-reorder is presentation-only unless order is meaningful downstream. Confirm whether item order is a business contract; if so, document it and test it.
• Silent scope creep — the field's convenience invites using it for data that later needs relational queries, creating a costly re-platform later. State the boundary explicitly in the design note.
• Vendor abandonment — mitigable by the small surface area, but only if the team can absorb the field in-house.

Ramp-up

• Developer ramp-up is near-trivial for anyone who has written a Nova field — a fluent, familiar API with copy-pasteable examples.
• QA and support ramp-up is the real cost: per-row inline errors, drag-and-drop (including the advertised keyboard path), chip overflow, tooltip-on-hover index badges, and EN/FR label toggling all need a checklist and accessibility verification.
• Admin-user comms are minimal; the interaction model is conventional, but document that list order is preserved and that item counts are constrained.
• Recommend a one-page internal runbook covering prerequisites, migration steps, validation ownership, asset-cache handling, and the escalation path if the vendor goes quiet.