feat: create reusable Hero component

[DavideIadeluca]

Fixes #4202

Changes proposed in this pull request:

• Create new reusable hero component to streamline the implementation of each variation

Reviewers should focus on:

• Tried to keep the core abstract implementation as lightweight as possible
• Perhaps some methods or the new class itself could be named better
• Does this change need to be documented?
• Are there any other Hero implementations i've missed?

Screenshot
DOM / UI should stay the same

Necessity

• Has the problem that is being solved here been clearly explained?
• If applicable, have various options for solving this problem been considered?
• For core PRs, does this need to be in core, or could it be in an extension?
• Are we willing to maintain this for years / potentially forever?

Confirmed

• Frontend changes: tested on a local Flarum installation.
• Backend changes: tests are green (run composer test).
• Core developer confirmed locally this works as intended.
• Tests have been added, or are not appropriate here.

Required changes:

• Related documentation PR: (Remove if irrelevant)

[DavideIadeluca]

FYI @imorland I just made a minor change I've had in mind. This PR is now good to go from my side

[imorland]

Thanks for this — the design is solid and consistent with the existing Modal pattern. This PR has been open for a while but I checked: the Laravel upgrade, LESS 5.x upgrade, and webpack changes that landed since opening do not affect any of this, so it is not stale. A few things to address before merge.

Summary of required changes:

• Add import './components/Hero' to forum.ts — explicit registration is the established convention and important for discoverability as a first-class extension point
• Add JSDoc to viewItems() — it is the primary structural extension point but has no documentation
• Remove ?? undefined from style={} in Hero.view() — redundant since style() already returns undefined, not null
• Fix Hero.view() return type from Mithril.Vnode | null to JSX.Element — the base never returns null
• Document the viewItems() → bodyItems() rename as a breaking change in the PR description and upgrade guide
• Add a note about UserPage's UserHero (via UserCard) being intentionally excluded

Also worth considering:

• The TagHero.className() approach of returning a space-separated string passed to classList() works with clsx 1.x but would silently break on a future upgrade to clsx 2.x, which does not split strings. See inline comment.
• Tests: the checklist item is unchecked. Snapshot/render tests confirming HTML structure is preserved would be valuable given the inheritance chain changes.

[imorland]

Breaking change notice needed. The current published dist-typings/forum/components/WelcomeHero.d.ts exposes viewItems() as a public method. Any third-party extension using extend(WelcomeHero.prototype, 'viewItems', ...) will silently stop firing after this rename.

Same applies to TagHero — its dist-typings also expose viewItems().

For a 2.x pre-release this is acceptable, but please:

1. Add an explicit note to the PR description calling this out
2. Ensure it is captured in the upgrade guide

[DavideIadeluca]

viewItems() is moved to the abstract class and can technically continue to be consumed the same way. In the grand scheme of things, this is a minuscule, non breaking change. Created a documentation PR for this anyways at flarum/docs#500

[imorland]

Empty interface extending another is fine for extensibility, but a brief comment would help clarify the intent to readers:

// Intentionally empty — extend this interface to add attrs for extensions.
export interface IMessagesPageHeroAttrs extends IHeroAttrs {}

[DavideIadeluca]

It's pretty common across the codebase to have empty interfaces like this — none of which have comments like this. If you would like we can follow up in a separate PR to streamline & create JSDoc's for interfaces