+
[c.slug, c]));
+
+/** Normalised label → slug (for mapping legacy free-text category values) */
+const _labelToSlug = Object.fromEntries(
+ CATEGORIES.map((c) => [c.label.toLowerCase().trim(), c.slug])
+);
+
+/**
+ * Get a Category by its slug.
+ * Returns `undefined` when not found — callers must handle this gracefully.
+ * @param {string} slug
+ * @returns {Category | undefined}
+ */
+export function getCategoryBySlug(slug) {
+ return _bySlug[slug];
+}
+
+/**
+ * Resolve a raw category string (as stored on a course document) to a known
+ * slug. Falls back to `null` when no match is found and logs a warning so
+ * that legacy / mismatched data is visible during development.
+ *
+ * @param {string | undefined | null} raw – the value stored on the course
+ * @returns {string | null} – a slug from CATEGORIES, or null
+ */
+export function resolveSlug(raw) {
+ if (!raw) return null;
+ const normalised = raw.toLowerCase().trim();
+ // Exact slug match
+ if (_bySlug[normalised]) return normalised;
+ // Exact label match
+ if (_labelToSlug[normalised]) return _labelToSlug[normalised];
+ // Partial label match (handles e.g. "Fiqh (Islamic Jurisprudence)" stored as just "Fiqh")
+ const partialMatch = CATEGORIES.find((c) =>
+ c.label.toLowerCase().includes(normalised) ||
+ normalised.includes(c.label.toLowerCase())
+ );
+ if (partialMatch) return partialMatch.slug;
+ console.warn(
+ `[categories] Unknown category value "${raw}" — falling back to "general" bucket.`
+ );
+ return null;
+}
+
+/**
+ * Get categories grouped by their parent group, as an array of objects.
+ * Useful for building grouped UIs (ComboBox, category hub grid).
+ *
+ * @returns {{ group: string, categories: Category[] }[]}
+ */
+export function getGroupedCategories() {
+ return CATEGORY_GROUPS.map((group) => ({
+ group,
+ categories: CATEGORIES.filter((c) => c.group === group),
+ }));
+}
+
+// ---------------------------------------------------------------------------
+// 4. islamicCategories shim
+// Keeps lib/data.js consumers working without change while ComboBox and
+// new pages switch over to this module's richer shape.
+// ---------------------------------------------------------------------------
+
+/**
+ * Drop-in replacement for the `islamicCategories` array from lib/data.js.
+ * Shape: [{ main: string, subcategories: string[] }]
+ */
+export const islamicCategoriesCompat = CATEGORY_GROUPS.map((group) => ({
+ main: group,
+ subcategories: CATEGORIES.filter((c) => c.group === group).map(
+ (c) => c.label
+ ),
+}));
+
+// ---------------------------------------------------------------------------
+// 5. Course-count derivation (client-side, backend-ready)
+// ---------------------------------------------------------------------------
+
+/**
+ * Given a flat array of course objects (each with a `category` string field),
+ * returns a map from slug → count.
+ *
+ * When the backend ships GET /api/courses/categories, replace this function
+ * body with a fetch call — the return type stays identical so callers need
+ * zero changes.
+ *
+ * @param {Array<{ category?: string }>} courses
+ * @returns {Record}
+ */
+export function getCategoryCounts(courses) {
+ /** @type {Record} */
+ const counts = {};
+ for (const course of courses) {
+ const slug = resolveSlug(course.category);
+ if (slug) {
+ counts[slug] = (counts[slug] || 0) + 1;
+ }
+ // Courses with unknown categories are counted under the fallback UI only,
+ // not attributed to any taxonomy slot.
+ }
+ return counts;
+}