Armada Laravel Package

Getting Started

Armada is a Blade component library (100+ anonymous components) that targets Laravel apps using Livewire for interactivity. It ships layout shells, navigation, forms, overlays, data display and server-rendered SVG charts, plus light/dark/system theming via --arm-* tokens. There is no JS chart library and no build step implied by the release notes, so it slots into a standard Blade/Livewire app.

Minimal steps:

1. Install the package (composer require), then check the service provider registers the armada component namespace and that the CSS entry point is published or autoloaded. Release notes don't specify an install command — read the package README for the exact CSS/JS inclusion tags before assuming anything.
2. Publish assets if the package expects it: php artisan vendor:publish --tag=armada-components is only for overriding individual views, not for required assets. Look for a separate config/asset publish tag.
3. Wrap your layout once. Replace your app shell with the Armada layout component (app shell + sidebar rail + mobile drawer/bottom nav), and put {{ $slot }} inside. Every page then inherits navigation, theming and the no-flash theme script.
4. Look first at: the layout component, one form component (input), the toaster, and the table. Those four cover ~80% of day-to-day usage and establish the conventions (props, slots, wire:model, error display).
5. First concrete use case: convert one existing CRUD screen. Swap your layout for the Armada shell, replace form fields with <x-armada::input wire:model="...">, drop the toaster into the layout, and rebuild the index as <x-armada::table>. Then verify on a phone width — tables become cards and pickers become bottom sheets automatically.

Note the two supported tag syntaxes: <armada:name> and <x-armada::name>. Pick one and enforce it in code review; mixing them in a codebase makes grepping and refactoring harder.

Implementation Patterns

Layout as the single integration point. Put the shell, toaster, theme script and icon sprite inclusion in one layout component. Any page that renders outside it (auth screens, error pages, PDF/email views) will miss theming and overlays. Create a minimal secondary layout for those rather than duplicating the script tags by hand.

Forms: lean on the automatic error display. Because components wire up wire:model and render validation errors themselves, keep your Livewire component's rules() and validate() calls as normal — don't add manual @error blocks around Armada fields unless you need bespoke markup. If your project uses a non-default error bag (e.g. $errorBag in multi-form pages), confirm the component picks it up before adopting it broadly; this is the most likely place to need a published override.

Toaster has three entry points — choose per context. Use the Livewire API for $this->dispatch(...)-style flash messages after actions, the flash API for redirect-based flows (session()->flash), and the JS API for purely client-side interactions (copy-to-clipboard, optimistic UI). Standardise on one helper per context so you don't end up with three different toast styles in one app.

Tables that become cards on mobile. Treat the responsive table as an intentional design constraint: design the mobile card representation at the same time as the desktop columns. Columns that don't translate to a card (e.g. wide numeric aggregates) need explicit hiding via props.

Charts are server-rendered SVG — pass data, not JS. Compute series in the Livewire component or a view composer and hand arrays to the chart component. This is a genuine advantage for dashboards behind auth (no client-side data leakage, no hydration flicker) and makes charts testable. Use wire:poll or Livewire refresh for updating charts rather than reaching for a JS library. For sparklines in stat cards, keep the dataset tiny — every chart is inline SVG in the DOM.

Kanban and event calendar are interactive islands. The kanban board has touch drag-and-drop; wire its move events to Livewire methods and persist server-side, then re-render. Treat these as the components most likely to need a published override, since drag semantics (ordering, cross-column rules) are domain-specific.

Command palette as a navigation layer. Register your app's routes/actions into the command palette early — it's cheap and it becomes the fastest way for power users to move around. Keep the action list generated from config or a navigation class rather than hardcoded in a Blade file.

Overriding, not forking. vendor:publish --tag=armada-components copies individual component views into resources/views/vendor/armada/.... Prefer publishing the smallest possible set: an override is a permanent maintenance obligation that you must diff against every new release. Before publishing, check whether a prop already covers your need — with 100+ components and dense prop surfaces, most tweaks (sizes, variants, icons) are configurable.

Theming. Set brand colours by overriding --arm-* custom properties in your app CSS rather than editing component views. Because Armada's styles live in cascade layers, your application CSS wins without !important — but only if your CSS isn't itself in a lower-priority layer. Keep app styles unlayered or in a layer declared after Armada's.

Language switcher + translations. English and Turkish ship in the box. For other locales, publish the lang files and add them; the switcher should be driven by your app's locale list, not the package's. Route the switch through your own SetLocale middleware so it persists as usual.

Privacy-friendly video facade. Use the YouTube/Vimeo facade component for any embedded media — it avoids third-party cookies until click and is the right default for GDPR-conscious apps. Don't hand-roll <iframe> embeds alongside it.

Gotchas and Tips

• Version requirements are unstated in the release notes. This is a Livewire-first package (wire:model, validation, toaster dispatch). Confirm the supported Livewire major (v3 vs v2) and any Alpine dependency before installing on an existing app. A Livewire major mismatch is the most likely reason a component silently doesn't behave.
• 1.0.0 is "first stable", so treat it as a new dependency, not a mature one. 100+ components landing at once means broad surface area and thin real-world mileage. Pin the version in composer.json and budget time for the first upgrade.
• Cascade layers can be defeated by your own CSS. If your app CSS is inside a layer declared before Armada's, or you use a utility framework with !important variants, overrides won't behave as advertised. Verify with devtools which layer wins before debugging the component.
• No-flash theming depends on an inline script in <head>. If you use a custom layout, an Inertia-style shell, or defer scripts, you'll get a flash on load. Copy the theme bootstrap from the provided layout exactly, and don't move it below your CSS.
• Bottom sheets on mobile can conflict with existing modals/dropdowns. If your app already has a JS modal library or a focus trap, stacking Armada's drawer/sheet on top produces focus-trap fights and scroll-lock that never releases. Consolidate on Armada overlays rather than running both.
• Tables-to-cards is CSS-driven. Custom cell renderers that assume <td> semantics (absolute positioning, colspan, nested tables) will break in card mode. Test at ~375px whenever you touch a table.
• Server-rendered SVG charts don't animate or zoom by default. If stakeholders expect interactive tooltips-on-hover with crosshairs, that's a custom override, not a prop. Set expectations before building dashboards on it.
• Publishing components freezes them. Published views won't receive upstream fixes. Keep a short list (in the repo, not in someone's head) of every published component and re-diff after each release. Delete overrides when upstream gains the prop you needed.
• 2,100+ icons means a sprite/registration question. Confirm how icons are loaded — a single sprite is fine; per-icon inline SVGs in long lists are not. A tree component with an icon per node is the stress case.
• Debugging order for a "component renders nothing" report: (1) tag syntax — <armada:name> vs <x-armada::name> and whether the namespace is registered; (2) layout missing the CSS; (3) a published override shadowing the vendor view; (4) Livewire version. In that order, it's usually the first.
• Extension points to reach for before overriding: design tokens, component props, the command palette action registry, and lang files. Overriding a Blade view is the last resort.
• Testing: anonymous components render fine in Blade/Pest view assertions, but overlay and drag components need browser testing (Dusk/Playwright). Assert on rendered SVG for charts rather than pixel snapshots — they'll churn on every data change.