Nova Jstree Laravel Package

Getting Started

This 1.0.0 release introduces a JsTree-backed field as the package's core capability, so treat it as the initial integration surface rather than a mature API.

1. Install the package with Composer and run the service provider/asset publishing steps it documents (vendor:publish for config and any JsTree CSS/JS assets).
2. Register the field where your admin/form layer expects custom fields (resource, form schema, or fieldset depending on the host package).
3. Point the field at a hierarchical data source — typically a self-referencing Eloquent model (categories, pages, menus) or a nested relationship.
4. First use case: replacing a flat select with a JsTree node picker for parent/child selection, then persisting the selected node IDs.

Look first at the field class itself (constructor options and setters), the published config, and any example resource in the package's README/tests. Because this is the first tagged release, the field's option surface is the best indicator of intended usage.

Implementation Patterns

• Single-node selection — configure the field to accept one node and map it to a parent_id-style foreign key. Validate the selected ID against the same tree source in a form request.
• Multi-node selection — map selected IDs to a pivot table or JSON column; normalize ordering before save so tree order is stable across requests.
• Relationship-backed trees — feed the field from a nested relationship and eager-load it (with('childrenRecursive')) to avoid per-node queries when serializing the tree.
• Scoped trees — filter the source query by tenant, site, or status before handing data to the field, rather than filtering client-side; this keeps the UI and validation consistent.
• Reusable field factory — wrap field construction in a small helper (e.g. JsTreeField::forModel(Category::class)) so multiple resources share the same source/validation rules.
• Form request pairing — put node-existence and depth rules in a dedicated request class so both create and update flows enforce the same constraints.
• Testing — assert on the persisted IDs and parent relationships rather than rendered HTML; JsTree's DOM is hard to assert against and brittle across asset versions.

Gotchas and Tips

• Assets are the usual failure point. JsTree depends on jQuery and its themes; a blank or unstyled tree almost always means unpublished assets, a missing script include, or a load-order problem. Check the browser network tab before debugging PHP.
• Data shape matters. JsTree expects a specific JSON node shape (id, parent, text). If your model uses different column names, transform explicitly; don't rely on the field to guess.
• First release = thin docs. With only one feature added and no changed/removed entries, expect undocumented edge cases around options and persistence. Read the field source and pin the version in composer.json until the API stabilizes.
• Self-referencing saves. Guard against setting a node as its own ancestor; add a validation rule for cycles, since the UI may not prevent it.
• Large trees. Serializing thousands of nodes into the field payload will hurt page weight; prefer lazy loading or server-side search scoping if the package supports it, otherwise pre-filter aggressively.
• Config quirks. Published config files are copied, not merged — after upgrading, diff the package's default config against your published copy to catch new keys (relevant as more field options arrive).
• Extension points. The field class is the place to subclass or decorate for custom option handling; keep customizations there rather than editing published assets, so upgrades stay clean.
• Debugging tip. Log the exact payload passed to the field when selection misbehaves; most "wrong node selected" reports trace back to duplicate IDs or unnormalized parent references.