Ui Kit Bundle Laravel Package

Getting Started

1. Install and register. composer require nowo-tech/ui-kit-bundle, then confirm the bundle is registered in config/bundles.php (Flex auto-registers Symfony bundles; if you're on a legacy or non-Flex app, add it manually). The package targets PHP ≥ 8.1 and Symfony 6/7/8 — check those constraints against your host app before pulling it in.
2. Wire the assets once. The bundle ships public assets under src/Resources/public. Install them with your normal pipeline (bin/console assets:install --symlink for the asset component, or the importmap/Encore equivalent documented in the README). Never edit the files in src/Resources/public — they're generated by the bundle's own asset build.
3. Pick your CSS framework mode first. The bundle exposes a class-helper strategy (bootstrap5, tailwind, foundation, custom, …). Set it to whatever your admin already uses before you write any markup. This is the single most consequential config choice: it determines the utility classes the macros emit.
4. Look here first, in this order:
   • the bundle's Twig macro directory and the nowo-ui-* CSS layer (the semantic contract you can restyle),
   • the class-helper config (framework mode + custom map),
   • the pagination/tabs/modal macros, since those carry the most markup assumptions.
5. First use case: take one existing admin list page and replace its hand-rolled pagination with the bundle's pagination macro, keeping the framework mode matched to your current CSS. That's a small, reversible change that validates the asset install, the Twig namespace, and the class helper in one go — before you commit to modals and tabs.

Implementation Patterns

Import macros per template, don't globalize. Import the specific macro file you need at the top of each template and alias it. Per-file imports keep the dependency visible and avoid a global TwigExtension you'd have to unwind later.

Treat nowo-ui-* as the stable API, framework utilities as the volatile layer. Write your own app partials using the semantic classes (nowo-ui-*) and let the helper translate. If you switch from Bootstrap 5 to Tailwind in two years, your markup survives; if you hardcode d-flex/mt-3 everywhere, it doesn't.

Compose, don't fork. The intended pattern is: shared admin layout → table/listing partial → pagination macro + modal macro + tabs macro. Pass plain arrays or DTOs into the macros. If a macro's markup doesn't fit, override the template via Symfony's bundle-override convention or extend the class map — not by copying macro bodies into your app.

Use custom mode as the integration seam for a design system. When your host app has its own tokens/utility naming, map the helper to it rather than fighting Bootstrap-flavoured output. Keep that map in one config file so a rebrand is a diff, not a hunt.

Keep modals and tabs progressively enhanced. Preserve the ids, data-* hooks, and ARIA attributes the bundle's frontend expects. If you swap content in via Turbo/HTMX, re-run the bundle's initializer after the DOM swap instead of assuming it re-binds.

Stay consistent across Nowo bundles. The stated purpose is a canonical kit for Nowo Symfony bundles and host apps. If you maintain several, consume the macros from every bundle rather than re-implementing a table in each — that's where the package pays for itself.

Test at the render boundary. A small Twig render test asserting that a macro emits the expected nowo-ui-* classes (and the right framework utility for the configured mode) catches most upgrade breakage cheaply. Match the bundle's existing test style rather than introducing a new framework.

One framework mode per application. The helper is app-global. Multi-tenant or multi-brand setups should run separate kernels/apps, not try to flip the mode per request.

Gotchas and Tips

• Maturity risk is the headline. Zero stars, zero dependents, a single publisher, and a release tag dated in the future. Treat it as an internal-first dependency: pin an exact version, read the diff on every bump, and keep the MIT license in mind as your fork escape hatch. Do not let it become load-bearing for a public-facing product without a maintenance plan.
• Stale installed assets are the #1 "my CSS didn't change" cause. assets:install copies; after a bundle upgrade, re-run it (or use --symlink) and clear cache. Check the installed copy under public/bundles/… before debugging templates.
• Class-helper mismatches look like broken macros. If pagination renders unstyled, verify the configured framework mode actually matches the CSS your layout loads — a Tailwind app with bootstrap5 mode produces plausible-looking but inert classes.
• Pagination silently drops query state if you don't pass it. The macro can only build links from what you give it. Forward the current route and the existing query parameters (filters, sort, page size) explicitly, or your users will lose their filters on page 2.
• Twig namespace errors are usually registration, not templates. If {% import %} fails, confirm the bundle is in bundles.php and run bin/console cache:clear before you go reading macro source.
• Don't edit src/Resources/public or the bundled templates in place. Both are regenerated/overwritten. Extension points, in preference order: config (class map / framework mode) → Symfony template override → upstream PR.
• Modals: duplicate ids are fatal. Rendering a modal macro inside a loop will collide on id. Render one modal per record with an id suffix, or one shared modal whose content you hydrate.
• Debugging checklist when something renders wrong: (1) bundle registered? (2) assets installed & cache cleared? (3) framework mode matches loaded CSS? (4) is the wrong class coming from your template rather than the macro? (5) does the rendered HTML still contain nowo-ui-* hooks?
• Config is app-global and visually breaking. Changing the framework mode in production is a full restyle. Gate it per-environment and never toggle it casually in a shared config file.
• Read UPGRADING/CHANGELOG before minor bumps. For a young, low-adoption bundle, backward-compatibility promises are best verified by reading the diff, not assumed.