Mary Laravel Package

Technical Evaluation

Architecture Fit

• Livewire-Centric Design: Remains fully aligned with Livewire-based Laravel applications, leveraging reactivity and component modularity. No architectural changes in this release.
• Tailwind/DaisyUI Foundation: Continues to rely on Tailwind CSS and DaisyUI, ensuring consistency with existing Laravel ecosystems. No breaking changes to CSS infrastructure.
• Component-Based: Modular approach unchanged; ideal for large-scale applications requiring UI consistency.
• Breaking Changes: None in 2.8.3. The release focuses on bug fixes (RTL support, Badge component logic) and does not introduce architectural shifts. Prior breaking changes (e.g., Livewire 4 compatibility) remain resolved in 2.8.x.

Integration Feasibility

• Livewire Dependency: Unchanged. Requires Livewire 4+ for full compatibility. No new constraints introduced.
• Tailwind CSS Requirement: No changes. Tailwind/DaisyUI setup remains mandatory.
• RTL Support Improvements:
  • Fix for Logical Margins: PR #1087 explicitly addresses RTL layout issues (e.g., margins, spacing) using Tailwind’s logical utilities (margin-inline-start, etc.).
  • Impact: Apps using right-to-left languages (e.g., Arabic, Hebrew) will see reduced layout quirks without additional configuration.
• CDN/Asset Dependencies: No changes. External CDNs (e.g., VanillaCalendarPro) remain optional but require explicit opt-in.
• Livewire 4 Compatibility: Confirmed stable in this release. No regressions reported.

Technical Risk

• RTL Layout Risks:
  • Mitigated: The logical margin fix (PR #1087) resolves a critical RTL gap. However, custom DaisyUI themes may still need validation for RTL-specific styles (e.g., icon alignment, form layouts).
  • Action: Test RTL flows in staging if targeting multilingual audiences.
• Badge Component Logic:
  • Fix for Value Logic: PR #1089 resolves a potential display bug in the Badge component (e.g., incorrect value rendering). Low-risk but worth verifying in apps using <x-mary-badge>.
• No New Dependencies: No external library additions, reducing risk of supply-chain vulnerabilities.
• Performance: No changes to component weight or rendering logic. Benchmarks from 2.8.2 remain applicable.

Key Questions for the TPM

1. RTL Adoption:
   • Does the app support RTL languages? If yes, verify the margin fix in PR #1087 with real content (e.g., Arabic test strings).
   • Are there custom DaisyUI plugins that might override RTL styles? Audit tailwind.config.js for conflicts.
2. Badge Component Usage:
   • Are <x-mary-badge> components used in production? If so, test the value logic fix (PR #1089) to confirm no regressions in critical paths.
3. Theming Consistency:
   • Have recent Tailwind/DaisyUI updates (e.g., v4.x) been applied? Ensure theme variables (e.g., colors, spacing) align with MaryUI’s defaults.
4. Localization Testing:
   • Beyond RTL, are there locale-specific components (e.g., DatePickers, NumberInputs) that need validation?
5. Rollback Plan:
   • Given the low-risk nature of 2.8.3, a rollback to 2.8.2 is trivial. Document the specific fixes (PR #1087, #1089) for future reference.

Integration Approach

Stack Fit

• Primary Fit: Unchanged. Laravel + Livewire + Tailwind/DaisyUI remains the optimal stack.
• RTL Enhancements: The logical margin fix (PR #1087) reduces friction for RTL-heavy applications without requiring stack modifications.
• Secondary Fit: Inertia.js and non-Livewire Laravel apps remain poor fits (no changes).

Migration Path

1. Assessment Phase:
   • RTL Audit: If targeting RTL languages, test the margin fix with sample content (e.g., Arabic placeholder text).
   • Badge Component Review: Scan codebase for <x-mary-badge> usage and validate the value logic fix (PR #1089).
2. Pilot Integration:
   • RTL Pages: Deploy 2.8.3 to RTL-specific routes first (e.g., /ar, /he) to validate fixes.
   • Badge Components: Replace any custom badge implementations with <x-mary-badge> to leverage the fix.
3. Sequencing Updates:
   • Step 1: Update composer.json to ^2.8.3 and run composer update.
   • Step 2: Rebuild Tailwind assets (npm run dev or npm run build) to ensure CSS alignment.
   • Step 3: Test RTL flows and Badge components in staging.
   • Step 4: Monitor for regressions in non-RTL paths (e.g., form submissions, modals).

Compatibility

Sequencing

1. Prerequisites:
   • Ensure Tailwind/DaisyUI are up-to-date (e.g., tailwindcss@^3.4, daisyui@^4.4).
   • Verify Livewire is on v4.x.
2. Core Update:

   composer require robsontenorio/mary:^2.8.3
   npm install -D tailwindcss@latest daisyui@latest
   

3. RTL Validation:
   • Add RTL-specific test strings to components (e.g., <x-mary-input placeholder="النص العربي">).
   • Check margins, padding, and alignment in RTL mode.
4. Badge Component Test:
   • Replace any custom badge logic with <x-mary-badge value="test">.
   • Verify values display correctly (e.g., no truncation or misalignment).
5. Regression Testing:
   • Run E2E tests for critical flows (e.g., form submissions, modal interactions).
   • Monitor performance metrics (LCP, CLS) post-update.

Operational Impact

Maintenance

• Pros:
  • RTL Fixes: PR #1087 and #1089 demonstrate active maintenance for edge cases.
  • No Breaking Changes: 2.8.3 is a safe upgrade with minimal risk.
  • Documentation: Fixes are linked to GitHub PRs; easy to reference for future troubleshooting.
• Cons:
  • RTL Customizations:
    • While PR #1087 improves RTL, custom DaisyUI themes may still require manual adjustments (e.g., icon positioning).
    • Action: Document RTL-specific overrides in tailwind.config.js.
  • Badge Component Quirks:
    • The fix in PR #1089 is targeted; apps with heavily customized badges may need additional validation.
  • Dependency Updates:
    • Tailwind/DaisyUI updates (e.g., v4.x) could indirectly affect MaryUI if theme variables change.
    • Mitigation: Pin Tailwind/DaisyUI to specific minor versions (e.g., ^3.4.1, ^4.4.2).
• Mitigation Strategies:
  • Version Locking: Use ^2.8.3 in composer.json to avoid auto-updates until stability is confirmed.
  • CI/CD Gates: Add RTL-specific tests to catch regressions (e.g., Arabic placeholder validation).
  • Fallback Plan: Maintain a patch queue for critical fixes if upstream lags (e.g., for non-RTL apps).

Support

• Community:
  • GitHub Issues: PR #1087 and #1089 are well-documented; community feedback is available.
  • Discord: Active for RTL-specific questions (e.g., "How to test logical margins?").
• Internal Resources:
  • RTL Test Cases: Create a shared test suite for RTL validation (e.g., using Laravel’s localization features).
  • Badge Component Guide: Document the fix (PR #1089) for onboarding new developers.
• Vendor Lock-In:
  • **Low