Mosaic

ernestdefoe

Mosaic

A polished, configurable Flarum 2 theme. Works as a standalone visual upgrade on any forum, with opt-in integrations for fof/best-answer, fof/reactions, ram0ng1/colored, and (when installed) linkrobins/support and ramon/marketplace.

Status: active development. LESS theme is complete, JS components are in place, design preview ships in preview/.

What you get

Tiled hero panel with title, search, and a configurable stats strip (Members / Discussions / Posts / Online Now — and Tickets Resolved when linkrobins/support is detected)
Category tiles below the hero — auto-populated from flarum/tags when installed
Configurable sidebar — Marketplace promo, Quick Actions (admin-editable rows: icon, label, URL), Top Contributors, Trending. Each panel can be hidden from the admin UI
Optional support-ticket styling — when linkrobins/support is enabled, the 5-state workflow (Open → In Progress → Awaiting You → Resolved → Closed), staff control bar, internal notes, and SLA pills all light up
Optional marketplace styling — when ramon/marketplace is enabled, the storefront, product cards, and cart get themed (verified against the real .MpShop-* DOM)
Best-answer highlight for fof/best-answer — full-width banner on the chosen reply
Reactions popup styled after ram0ng1/avocado's cascade pattern
Tag-coloured borders for ram0ng1/colored on the discussion list and posts
Full dark mode via Flarum 2's native [data-theme^=dark] selector
DM Sans typography, organic 14px radii, calm primary palette

Install

composer require ernestdefoe/mosaic
php flarum cache:clear

Then enable in Admin → Extensions → Mosaic.

Configure

All theme settings live in Admin → Extensions → Mosaic:

Hide sidebar widgets — toggle Marketplace promo / Quick Actions / Top Contributors / Trending individually
Quick Actions editor — dynamic row editor for the sidebar's Quick Actions card. Each row is an icon class, a label, and a URL. Defaults to Start a Discussion / Browse Tags / Recent Activity for any Flarum install, and surfaces Open a Support Ticket / Visit the Marketplace extras when those extensions are detected
Section URL overrides — point the auto-detected support / marketplace links elsewhere if you've mounted them on non-default paths

Develop

cd js
npm install
npm run dev      # watch mode
npm run build    # production

The frontend uses flarum-webpack-config v3 — js/forum.js and js/admin.js are auto-discovered, with webpack running from js/ and emitting to js/dist/. Compiled bundles in js/dist/ are committed because Flarum extensions installed via Composer ship prebuilt assets.

Structure

mosaic/
├── composer.json       # Flarum 2 extension manifest
├── extend.php          # PHP extender — registers forum/admin frontends + settings bridge
├── src/Api/
│   ├── AddForumSettings.php       # SettingsRepositoryInterface helpers
│   └── AddForumStatistics.php     # Member/online/resolved counts
├── js/
│   ├── package.json
│   ├── webpack.config.js
│   ├── forum.js / admin.js        # entries (discovered by webpack)
│   ├── dist/                      # compiled bundles, committed
│   └── src/
│       ├── forum/
│       │   ├── index.js                       # initializer + IndexPage hooks
│       │   └── components/
│       │       ├── HeroPanel.js               # branded hero + stats strip
│       │       ├── CategoryTiles.js           # category grid
│       │       ├── SidebarPanels.js           # Marketplace promo / QA / contributors / trending
│       │       ├── MarketplacePromoCard.js    # sidebar CTA
│       │       ├── HeaderNav.js               # primary nav items
│       │       └── SectionHeader.js
│       └── admin/
│           ├── index.js
│           └── extend.js                      # Admin settings (visibility, URLs, QA editor)
├── less/
│   ├── forum.less / admin.less    # entries
│   ├── tokens.less                # CSS custom properties
│   ├── base.less, header.less, hero.less, categories.less, discussions.less,
│   │   post.less, sidebar.less, composer.less, support.less, marketplace.less,
│   │   reactions.less, colored.less, layout.less, dark.less
├── locale/en.yml
└── preview/                       # static HTML mockup (design source of truth)

Pairing with optional extensions

| Surface | Source | Where styled |
|---|---|---|
| Discussion list / detail | Flarum core | discussions.less, post.less |
| Tags (coloured borders) | ram0ng1/colored | colored.less |
| Reactions popup | fof/reactions | reactions.less |
| Best-answer highlight | fof/best-answer | post.less .Post--bestAnswer |
| Tickets (5-state workflow, internal notes) | linkrobins/support (optional) | support.less |
| Marketplace storefront / cards / cart | ramon/marketplace (optional, paid) | marketplace.less |

Each integration's LESS is a no-op when the source extension isn't installed — Mosaic stays clean on a vanilla Flarum.

Design preview

The preview/ directory ships a static HTML mockup of every surface — open preview/index.html directly or run npx serve preview/ to inspect the design without a Flarum install. Treat that mockup as the visual source of truth.

Credits

DM Sans by Colophon Foundry, via Google Fonts
Font Awesome 7 for iconography
Visual cues borrowed from Avocado by ramon

Support

Questions, bug reports, and feature requests:

Support forum: https://ernestdefoe.online
Issues: ernestdefoe/mosaicissues

License

MIT — see LICENSE.

ernestdefoe

mosaic 3.1.0

What's Changed

A code-audit release — the hero stats are now accurate, plus internal robustness and type-safety fixes.

Fixed

Accurate hero counts. The "Discussions" and "Posts" tiles previously fell back to counting only the discussions loaded on the current page — so every visitor saw a small, misleading number (e.g. "20 Discussions"). They're now backed by real, cached forum-wide totals computed server-side.
Dead "extra nav links" branch removed. A header-nav feature that was never wired to any setting or admin control has been removed.
Fallback category tiles now navigate. On a fresh install without flarum/tags, the six placeholder category tiles linked to # and did nothing; they now go to the discussion index.

Internal

The statistics service no longer depends on a low-level database connection interface, and the support-extension table probe is now resolved through Flarum's own model connection (the DB/Schema facades aren't usable in Flarum).
The shared translate() helper, previously copy-pasted into three components, is now a single utility.
Every frontend component is fully TypeScript type-checked — the @ts-nocheck escape hatches are gone, so attribute typos are caught at compile time.

View release on GitHub

ernestdefoe

mosaic 3.2.0

What's Changed

A code-audit release — the contributor/trending panels now work forum-wide, plus internal robustness fixes.

Fixed

Top Contributors and Trending panels show real forum-wide data. They previously ranked only the handful of records the current page had loaded (≈20 discussions, often 0 users), so they were usually empty or unrepresentative — and the admin "top contributors" path never worked because its data was never sent to the frontend. Both are now computed and cached server-side and sent as forum attributes. Trending is computed against guest visibility, so it never surfaces a discussion a guest couldn't already see.
Marketplace promo + hero stat labels are translatable. They were hardcoded English; they now route through the locale file so translators' overrides take effect.

Internal

The forum-payload fields are built by a container-injected class instead of manual service resolution.
Resolved-ticket counting uses a small Eloquent read-model rather than a borrowed raw database connection.
The hero pill-row no longer instantiates a core component out of its lifecycle to read its nav items; it builds its own row.
Removed an unused duplicate component and de-duplicated the composer-open helper into a single utility.

View release on GitHub

ernestdefoe

mosaic 3.3.0

What's Changed

Two visual fixes in the discussion list and the sidebar contributor panel.

Fixed

Top Contributors avatars — the panel now shows actual user profile photos when members have uploaded an avatar. Previously a PHP method-call bug ($u->avatarUrl() rather than $u->avatar_url) silently returned null for every user, falling back to colour-coded initials every time.
Tag pills beside the discussion title — tag chips now appear on the same line as the discussion title rather than in a separate full-width row below it. Uses display: contents on the info <ul> to promote tag <li> elements into the title row's flex context, with an invisible row-break sentinel pushing metadata (poster, time) to the next row.

View release on GitHub

ernestdefoe

mosaic 3.4.0

What's Changed

Adds blog post creation entry points and section navigation when linkrobins/blog is installed.

Added

Blog nav pill in the hero pill-row (uses the admin-configured blog nav label/icon, falling back to "Blog" with a feather icon).
"Write a Blog Post" in the Quick Actions sidebar panel — shown to members with permission to write posts.
"Write a Post" button in the site header on /blog routes — gives authors a direct path to the compose editor on the blog's own pages, which use the blog extension's layout rather than the forum index.
Section nav pills ("Discussions" / "Blog") above the blog index and category pages, so the blog feels like a first-class section — useful if you set the blog as your landing page.

All entry points are permission-gated (canCreateBlogPost) and only appear when the blog extension is present.

Fixed

A blank-page crash when navigating to the blog via the in-app nav pill. The blog-page nav wrapper now keys its fragment consistently, resolving a Mithril "vnodes must either all have keys or none have keys" error that only triggered on client-side route transitions.

View release on GitHub

ernestdefoe

mosaic 3.4.1

Added

Hero nav: a pill for each Page Builder content type (e.g. Articles) now appears in the hero navigation, linking to its /c/{slug} listing. Read from the pagebuilderContentTypes forum attribute, so it works automatically for any content type you define.

View release on GitHub

Claude_Bot

mosaic 3.4.2

Floxum audit hardening. Removed an unused RuntimeException import, locale-aware number formatting (dropped hardcoded en-US), and wired the sidebar card titles + quick-action labels through the translator. Two LOW findings (the app.routes wrapping and the openComposer DOM/rAF shim) are intentionally retained with documented rationale.

View release on GitHub

ernestdefoe

mosaic 3.4.3

Admin inputs keep the theme's styling. The rules were being lost to the cascade, so inputs in the admin area fell back to unstyled defaults. Scoping them under the app root puts the theme back in charge.

The PHP requirement is declared explicitly. A Flarum 2 extension has to ask for PHP ^8.3: with ^8.2 against core ^2.0 the constraint cannot be satisfied, and Composer reports that as a conflict across the whole dependency set rather than naming the extension — which makes it unpleasant to diagnose from the error alone.

View release on GitHub