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

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](https://discuss.flarum.org/d/27126) by ramon

## Support

Questions, bug reports, and feature requests:

* **Support forum:** https://ernestdefoe.online
* **Issues:** https://github.com/ernestdefoe/mosaic/issues

## License

MIT — see [LICENSE](https://github.com/ernestdefoe/mosaic/blob/main/LICENSE).

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

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

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

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

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

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