I Reports Laravel Package

Getting Started

This release is additive plus a bug fix — no breaking changes — so upgrading from 2.1.0 is a composer update away.

1. Update the package and, if you have a published config, diff it against the new stub (php artisan vendor:publish --tag=config --force into a scratch copy, or just open the package's config/*.php) — you want the new screen_style block.
2. Clear cached config: php artisan config:clear.
3. Confirm the fix: if you render reports in inline mode inside a dark page, dark cell text on a dark background is gone in 2.1.1. That's the first thing to verify, because it's the only behaviour change.

First real use case: put a report in an iframe inside your existing Blade layout, and let Bootstrap 5.3 drive the theme. Set data-bs-theme="dark" (or light) on <html> or any ancestor of the iframe — the viewer reads it and paints itself accordingly. Open the same report URL directly in a tab and it will follow the OS colour scheme instead, which is exactly what you want for "open in new window" links and emailed report URLs.

Where to look first: the config file (default_style, now screen_style) and the --ir-* CSS variable definitions. Those two are the whole theming surface.

Implementation Patterns

Keep default_style as the source of truth, override selectively in screen_style. The two configs are near-parallel by design: light screen_style values match default_style. So define your palette once in default_style (it still drives print, PDF and Excel), then in screen_style set only the keys that must differ for dark mode — headers, totals rows, zebra striping, warning/negative-number colours. Any key you leave out or set to null falls back to default_style, so a partial screen_style array is a valid and low-maintenance setup.

Theme via Bootstrap attributes, not classes. The iframe observes data-bs-theme on the embedding page and swaps live. A theme toggle that just adds a .dark class to <body> will leave the iframe stuck on its old palette. If you use a custom toggle (Alpine, Livewire, a settings drawer), write the attribute:

document.documentElement.setAttribute('data-bs-theme', isDark ? 'dark' : 'light')

Style through --ir-* variables when you need more than the config offers. Cell colours in the viewer are built on these variables, so overriding them on a wrapping element gives you per-page or per-tenant theming without touching config. Define overrides under both [data-bs-theme="dark"] and [data-bs-theme="light"] (plus a @media (prefers-color-scheme: dark) block for standalone viewing) so the three entry paths — embedded light, embedded dark, standalone — all resolve.

Treat the screen and the export as two designs. A sensible workflow: build default_style for paper first (black text, high contrast, no near-white-on-white), get the PDF and Excel output right, then layer screen_style on top purely for the on-screen viewer. Reports that look great on a dark dashboard and wash out in a printed PDF are the common failure here, and the package won't warn you.

Inline vs iframe is a layout decision, not a theming one. Iframe mode isolates the report's CSS from your app shell — prefer it when your admin theme is heavily customised. Inline mode shares the page's cascade, which makes --ir-* overrides trivial but means your app's global table/color rules can leak in. Pick per-route and stay consistent.

Gotchas and Tips

• screen_style does not affect exports. Print, PDF and Excel deliberately keep default_style. If a user reports "the downloaded file looks different from the screen", that's the intended contract, not a bug — document it so it doesn't come back as a ticket.
• null means "inherit", not "unstyled". Setting a key to null falls back to default_style. To actually remove a style you need the same value as your neutral cell, not null.
• The iframe watches the attribute, so attribute toggles must be on an ancestor of the iframe, not inside it. Toggling data-bs-theme on the iframe element itself is fine too, but then it stops following the host page.
• Embedding inside a non-Bootstrap app means no data-bs-theme anywhere, so the iframe falls back to the OS scheme. That's usually desirable, but if you want a fixed theme, set the attribute explicitly on a wrapper — don't rely on defaults.
• Standalone viewing uses prefers-color-scheme, which you can't override from config. Test with the OS or devtools emulation before shipping; a report that's legible in embedded dark mode can still be unreadable in standalone dark if you only tested one path.
• Upgrading with a published config requires a manual merge. The new screen_style key won't appear on its own; if it's absent, the viewer just uses default_style everywhere — silently correct-looking, but you get none of the new behaviour.
• CSS variable overrides must load after the package stylesheet. In a compiled Vite bundle this is ordering-dependent; a scoped selector with higher specificity is more reliable than hoping for cascade order.
• Watch for CSS-variable support in your PDF renderer. Dompdf and friends have patchy custom-property support, which is very likely why exports stayed on plain default_style. Don't try to "unify" the two configs by feeding screen_style into PDFs.
• After the 2.1.1 fix, re-check inline mode in dark. If you had worked around the dark-on-dark text with a local override, that patch is now redundant and may fight the new behaviour — remove it.