I Reports Laravel Package

Product Decisions This Supports

• Dark-mode parity for embedded reporting is now a viable requirement, not a deferral. If your product ships a light/dark theme toggle (Bootstrap 5.3 data-bs-theme is the common pattern), the on-screen report viewer can inherit it automatically instead of forcing you to build a themed report surface or accept a jarring white panel inside a dark UI. That removes a recurring "reports look broken in dark mode" ticket class and a common reason to keep reports behind a separate tab.
• Build vs buy tilts toward buy for presentation-layer theming. screen_style with --ir-* CSS variables means theme-aware cell styling is configuration, not custom CSS overrides you maintain against the package's markup. Choosing this package lets you spend design effort on your own design tokens rather than reverse-engineering a report renderer's internals on each upgrade.
• Use cases that benefit most: customer-facing analytics dashboards, admin/ops consoles with dark-mode users, embedded reporting inside SaaS apps where the report is one panel among many, and any workflow where users move between a themed app shell and a report viewer in the same session.
• Roadmap implication — bounded scope, clear boundary. Theming applies only to the on-screen viewer (iframe and inline). Print, PDF, and Excel deliberately keep default_style. That is a sensible product decision (exports are documents, not UI), but it means you must not promise "branded dark exports" downstream; treat export styling as a separate initiative with its own budget.
• Low-risk incremental upgrade. This is a minor/patch release adding capability plus a contrast fix, with no noted breaking changes or deprecations — the kind of change you can fold into a normal sprint rather than a migration project. It also removes a known accessibility defect (dark text on dark background in inline mode), which may close an internal accessibility or QA finding without engineering effort.

When to Consider This Package

Adopt / upgrade when:

• Your application shell uses Bootstrap 5.3 theming, or you can set data-bs-theme on the embedding page — the iframe picks it up and reacts live, which is the cheapest possible integration.
• You embed reports in a themed product and have had dark-mode or contrast complaints; the inline-mode fix addresses the most visible failure directly.
• You need theme-aware styling that survives package upgrades — --ir-* variables with null fallback to default_style give you a safe, layered override model.
• You are already on the package and want the accessibility fix; the change is additive and low-blast-radius.
• You need one viewer that works both embedded (follows the host page) and standalone (follows the OS colour scheme) — that dual behaviour reduces per-deployment configuration.

Look elsewhere or defer when:

• Exports are the product. If stakeholders care most about PDF/Excel fidelity and branding, this release doesn't move them; print/PDF/Excel styling is unchanged and still governed by default_style.
• You are not on Bootstrap 5.3. The live-switching behaviour depends on data-bs-theme; on another design system or an older Bootstrap you would be managing theme state and CSS variables yourself, and the value drops sharply.
• You need granular per-column or per-tenant theming logic beyond what a config map expresses — evaluate whether screen_style covers your cases before committing.
• You require guaranteed semantic-versioning stability across a major upgrade; verify current version and changelog against your constraint before planning.
• Dark mode is not on your users' critical path and you are mid-migration — the fix is worthwhile but not urgent enough to justify change-window risk.

How to Pitch It (Stakeholders)

For executives: This update makes the on-screen report viewer respect the product's light and dark themes automatically. It closes a visible quality gap — reports previously rendered as a bright, off-theme panel for dark-mode users, with one case of unreadable text — and it does so through configuration rather than custom engineering. There is no migration cost, no breaking change, and no new system to operate. The practical outcome: fewer cosmetic defects in customer-facing dashboards, a consistent experience for the growing share of users on dark mode, and no design debt created in our own codebase to achieve it. Scope is deliberately limited to the interactive viewer; exported PDF and Excel files are unchanged, so any expectations about branded exports should be handled as separate work.

For engineering: Small, additive release. The viewer reads data-bs-theme from the embedding page for iframe mode and switches live on change; standalone it defers to the OS preference. Styling is now driven by --ir-* CSS variables via a new screen_style config key, with null per-key fallback to default_style, so existing overrides keep working and our customisations stay upgrade-safe. The dark-mode contrast bug in inline mode is fixed. Print/PDF/Excel paths are untouched and continue to use default_style — no export regressions expected. Recommended action: minor version bump, verify visually in both themes in our embedding context, and add a dark-mode case to the report QA checklist so this doesn't silently regress.