Mary Ui Optimized Laravel Package

Getting Started

This is a performance-optimized fork of Mary UI, so treat it as a drop-in component library for Laravel + Blade + Livewire with DaisyUI/Tailwind styling.

1. composer require the package, then run the install command (php artisan mary:install) to wire up Tailwind/DaisyUI and publish the config.
2. Add the theme/stylesheet entry to your tailwind.config.js and layout <head> as instructed by the published config.
3. Drop a component into any Blade view: <x-mary-button label="Save" />, <x-mary-card>…</x-mary-card>, <x-mary-input wire:model="name" />.

Where to look first:

• The base component class and its UUID trait — this is the only meaningful change in v1.0.0 and everything else inherits from it.
• The published config file (theme, prefix, component toggles).
• One reference component (Button is smallest) to see how $uuid is consumed via id/for/aria-*.

First real use case: a Livewire form panel — inputs, a submit button, and a modal for confirmation. That exercises UUID generation, wire:model binding, and the Alpine-backed components in one screen.

Implementation Patterns

Standard Blade usage. Components are anonymous/class-backed Blade components under the mary namespace. Prefer the documented attribute API (label, icon, variant, hint) over injecting raw classes; the fork's perf gains come from streamed initialization, so overriding internals is where you'll lose them.

Livewire forms. Bind with wire:model directly on x-mary-input, x-mary-select, x-mary-datetime. Use x-mary-form for error-bag wiring and x-mary-errors for display. Keep validation rules server-side; the components do not validate.

Modals and drawers. Use the Livewire-driven pattern (wire:model="showModal" plus x-mary-modal) rather than hand-rolled Alpine state — these components depend on the generated $uuid for their x-data/x-ref wiring, and fighting that is not worth it.

Tables and charts. x-mary-table with :headers and a @scope-style slot, or use the built-in header/row API for simple cases. Charts take a :dataset array and render client-side — don't expect them to update without a Livewire round trip plus wire:key.

Wrapping components. When you build your own component around a Mary one, extend the package's base class (or reuse its UUID trait) so nested components keep distinct ids rather than inheriting a parent's.

Theming. Do it through CSS variables / the published theme config, not by publishing and editing component views — overridden views won't receive future perf fixes.

Gotchas and Tips

The UUID change is the real breaking change. v1.0.0 replaces md5(serialize($this)) with a per-request incrementing counter (btn-1, btn-2, …). Consequences:

• Ids are no longer content-derived or stable between requests. Any e2e selector, Dusk test, JS snippet, or analytics hook keyed on a hashed id breaks. Select by data-*, name, or role instead.
• Duplicate ids if you cache rendered HTML. Blade fragment caching, response caching, or @cache blocks will replay the same btn-1 on every request, producing invalid duplicate ids on pages that also render live components. Don't cache component markup that relies on $uuid.
• Livewire DOM diffing. Because ids shift on re-render, always give repeated/looped components a stable wire:key. Without it, Alpine state (open dropdowns, modal scroll) can attach to the wrong node after a morph.
• Octane/long-lived workers. A counter that isn't reset per request will keep climbing — harmless for uniqueness, but it defeats the memory/consistency intent and can leak into snapshot tests. Verify the counter resets (typically in a middleware or service provider) before trusting id values in tests.
• Assertions like assertSee('btn-1') are now order-dependent: reordering components in a view changes the numbers.

Debugging. dump($this->uuid) inside a component view is the fastest check. If ids look wrong, confirm you're not extending an older base class or overriding a component view that was copied before the upgrade.

Config quirks. Publishing views/config pins you to that snapshot; re-publish after upgrading to pick up the counter-based internals. Check the prefix setting before writing selectors — a custom prefix changes the id pattern entirely.

Upgrade checklist. Search the codebase for #[id^=, md5(, hardcoded numeric ids, and any test asserting on generated ids. Run the e2e suite against a page that renders many components to confirm nothing depended on the old deterministic hashes.

Extension point. If you need stable, content-derived ids for a specific component, override the UUID method on that one class rather than reverting the base — you keep the ~70% initialization win everywhere else.