@sp-days-framework/docusaurus-plugin-interactive-tasks 1.0.0

package/lib/utils/logger.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Interactive Tasks Plugin Logger
+ * Wraps Docusaurus logger for consistent build-time logging
+ * This is for Node.js build-time only (plugins, webpack)
+ */
+/**
+ * Log info message
+ * Format: [INFO] [Interactive Tasks] message
+ */
+export declare function logInfo(message: string): void;
+/**
+ * Log warning message
+ * Format: [WARNING] [Interactive Tasks] message
+ */
+export declare function logWarn(message: string): void;
+/**
+ * Log error message
+ * Format: [ERROR] [Interactive Tasks] message
+ */
+export declare function logError(message: string, error?: any): void;
+/**
+ * Log success message
+ * Format: [SUCCESS] [Interactive Tasks] message
+ */
+export declare function logSuccess(message: string): void;
+/**
+ * Format a file path for logging (with blue underline)
+ */
+export declare function formatPath(filePath: string): string;
+/**
+ * Format a number for logging (with cyan color)
+ */
+export declare function formatNumber(num: number): string;
+/**
+ * Format code/identifier for logging (with cyan color)
+ */
+export declare function formatCode(code: string): string;
+//# sourceMappingURL=logger.d.ts.map

package/lib/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;GAGG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,GAAG,IAAI,CAO3D;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/lib/utils/logger.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Interactive Tasks Plugin Logger
+ * Wraps Docusaurus logger for consistent build-time logging
+ * This is for Node.js build-time only (plugins, webpack)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logInfo = logInfo;
+exports.logWarn = logWarn;
+exports.logError = logError;
+exports.logSuccess = logSuccess;
+exports.formatPath = formatPath;
+exports.formatNumber = formatNumber;
+exports.formatCode = formatCode;
+const logger_1 = __importDefault(require("@docusaurus/logger"));
+const PLUGIN_PREFIX = "Interactive Tasks";
+/**
+ * Log info message
+ * Format: [INFO] [Interactive Tasks] message
+ */
+function logInfo(message) {
+    logger_1.default.info `[${PLUGIN_PREFIX}] ${message}`;
+}
+/**
+ * Log warning message
+ * Format: [WARNING] [Interactive Tasks] message
+ */
+function logWarn(message) {
+    logger_1.default.warn `[${PLUGIN_PREFIX}] ${message}`;
+}
+/**
+ * Log error message
+ * Format: [ERROR] [Interactive Tasks] message
+ */
+function logError(message, error) {
+    if (error) {
+        logger_1.default.error `[${PLUGIN_PREFIX}] ${message}`;
+        console.error(error);
+    }
+    else {
+        logger_1.default.error `[${PLUGIN_PREFIX}] ${message}`;
+    }
+}
+/**
+ * Log success message
+ * Format: [SUCCESS] [Interactive Tasks] message
+ */
+function logSuccess(message) {
+    logger_1.default.success `[${PLUGIN_PREFIX}] ${message}`;
+}
+/**
+ * Format a file path for logging (with blue underline)
+ */
+function formatPath(filePath) {
+    return logger_1.default.path(filePath);
+}
+/**
+ * Format a number for logging (with cyan color)
+ */
+function formatNumber(num) {
+    return logger_1.default.cyan(num);
+}
+/**
+ * Format code/identifier for logging (with cyan color)
+ */
+function formatCode(code) {
+    return logger_1.default.code(code);
+}
+//# sourceMappingURL=logger.js.map

package/lib/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;AAUH,0BAEC;AAMD,0BAEC;AAMD,4BAOC;AAMD,gCAEC;AAKD,gCAEC;AAKD,oCAEC;AAKD,gCAEC;AA5DD,gEAAwC;AAExC,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAE1C;;;GAGG;AACH,SAAgB,OAAO,CAAC,OAAe;IACrC,gBAAM,CAAC,IAAI,CAAA,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,SAAgB,OAAO,CAAC,OAAe;IACrC,gBAAM,CAAC,IAAI,CAAA,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,SAAgB,QAAQ,CAAC,OAAe,EAAE,KAAW;IACnD,IAAI,KAAK,EAAE,CAAC;QACV,gBAAM,CAAC,KAAK,CAAA,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC;QAC5C,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;SAAM,CAAC;QACN,gBAAM,CAAC,KAAK,CAAA,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC;IAC9C,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,UAAU,CAAC,OAAe;IACxC,gBAAM,CAAC,OAAO,CAAA,IAAI,aAAa,KAAK,OAAO,EAAE,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,SAAgB,UAAU,CAAC,QAAgB;IACzC,OAAO,gBAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,GAAW;IACtC,OAAO,gBAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,SAAgB,UAAU,CAAC,IAAY;IACrC,OAAO,gBAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC"}

package/lib/utils/storage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Storage utilities for task persistence
+ */
+import type { TasksState } from "../contexts/TaskContext";
+/**
+ * Check if we're in a browser environment
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Load tasks from localStorage
+ */
+export declare function loadTasksFromStorage(): TasksState;
+/**
+ * Save tasks to localStorage
+ */
+export declare function saveTasksToStorage(tasks: TasksState): void;
+/**
+ * Load auto-collapse preference from localStorage
+ */
+export declare function loadAutoCollapseFromStorage(): boolean;
+/**
+ * Save auto-collapse preference to localStorage
+ */
+export declare function saveAutoCollapseToStorage(autoCollapse: boolean): void;
+/**
+ * Generate a task key for storage
+ * Format: task-{pluginId}-{docId}-{taskNumber}-{encodedName}
+ *
+ * Encodes the task name to be URL-safe and consistent with the task registry.
+ * Special characters are replaced with dashes to ensure compatibility.
+ */
+export declare function generateTaskKey(pluginId?: string, docId?: string, taskNumber?: number, name?: string): string;
+//# sourceMappingURL=storage.d.ts.map

package/lib/utils/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/utils/storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAK1D;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAInC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,CAkBjD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAa1D;AAED;;GAEG;AACH,wBAAgB,2BAA2B,IAAI,OAAO,CAerD;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,OAAO,GAAG,IAAI,CAarE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,CAAC,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAeR"}

package/lib/utils/storage.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Storage utilities for task persistence
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBrowser = isBrowser;
+exports.loadTasksFromStorage = loadTasksFromStorage;
+exports.saveTasksToStorage = saveTasksToStorage;
+exports.loadAutoCollapseFromStorage = loadAutoCollapseFromStorage;
+exports.saveAutoCollapseToStorage = saveAutoCollapseToStorage;
+exports.generateTaskKey = generateTaskKey;
+const STORAGE_KEY = "sp-tasks";
+const AUTO_COLLAPSE_KEY = "autoCollapseCompletedTasks";
+/**
+ * Check if we're in a browser environment
+ */
+function isBrowser() {
+    return (typeof window !== "undefined" && typeof window.localStorage !== "undefined");
+}
+/**
+ * Load tasks from localStorage
+ */
+function loadTasksFromStorage() {
+    if (!isBrowser()) {
+        return {};
+    }
+    try {
+        const stored = localStorage.getItem(STORAGE_KEY);
+        if (stored) {
+            return JSON.parse(stored);
+        }
+        return {};
+    }
+    catch (error) {
+        console.error("[Interactive Tasks] Failed to load tasks from storage:", error);
+        return {};
+    }
+}
+/**
+ * Save tasks to localStorage
+ */
+function saveTasksToStorage(tasks) {
+    if (!isBrowser()) {
+        return;
+    }
+    try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(tasks));
+    }
+    catch (error) {
+        console.error("[Interactive Tasks] Failed to save tasks to storage:", error);
+    }
+}
+/**
+ * Load auto-collapse preference from localStorage
+ */
+function loadAutoCollapseFromStorage() {
+    if (!isBrowser()) {
+        return false;
+    }
+    try {
+        const stored = localStorage.getItem(AUTO_COLLAPSE_KEY);
+        return stored === "true";
+    }
+    catch (error) {
+        console.error("[Interactive Tasks] Failed to load auto-collapse preference:", error);
+        return false;
+    }
+}
+/**
+ * Save auto-collapse preference to localStorage
+ */
+function saveAutoCollapseToStorage(autoCollapse) {
+    if (!isBrowser()) {
+        return;
+    }
+    try {
+        localStorage.setItem(AUTO_COLLAPSE_KEY, String(autoCollapse));
+    }
+    catch (error) {
+        console.error("[Interactive Tasks] Failed to save auto-collapse preference:", error);
+    }
+}
+/**
+ * Generate a task key for storage
+ * Format: task-{pluginId}-{docId}-{taskNumber}-{encodedName}
+ *
+ * Encodes the task name to be URL-safe and consistent with the task registry.
+ * Special characters are replaced with dashes to ensure compatibility.
+ */
+function generateTaskKey(pluginId, docId, taskNumber, name) {
+    // Convert name to a URL-safe slug: lowercase, replace spaces and special chars with dashes
+    const encodedName = name
+        ? name
+            .toLowerCase()
+            .replace(/\s+/g, "-") // Replace spaces with dashes
+            .replace(/[^a-z0-9-]/g, "-") // Replace special chars with dashes
+            .replace(/-+/g, "-") // Collapse multiple dashes
+            .replace(/^-|-$/g, "") // Remove leading/trailing dashes
+        : "unnamed";
+    const pluginStr = pluginId || "unknown";
+    const docStr = docId || "unknown";
+    const taskStr = taskNumber !== undefined ? taskNumber : "unknown";
+    return `task-${pluginStr}-${docStr}-${taskStr}-${encodedName}`;
+}
+//# sourceMappingURL=storage.js.map

package/lib/utils/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/utils/storage.ts"],"names":[],"mappings":"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"}

package/lib/utils/useDocTaskStats.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Custom hook for getting task statistics for a specific document
+ * Combines data from task registry (metadata) and task context (completion states)
+ */
+import type { BadgeConfig } from "../contexts/TaskContext";
+export interface DocTaskStats {
+    /** Total number of tasks in this doc */
+    totalTasks: number;
+    /** Number of completed tasks */
+    completedTasks: number;
+    /** Whether this doc has a custom section name */
+    hasSectionName: boolean;
+    /** The section name (e.g., "Module 1") or falls back to title */
+    sectionName: string;
+    /** The document title */
+    title: string;
+    /** The permalink to this doc */
+    permalink: string;
+    /** Completion percentage (0-100) */
+    percentage: number;
+    /** Whether all tasks are completed */
+    isComplete: boolean;
+    /** Whether this doc has any tasks at all */
+    hasAnyTasks: boolean;
+    /** Badge customization configuration */
+    badgeConfig?: BadgeConfig;
+}
+/**
+ * Get task statistics for a specific document
+ *
+ * @param docId - The document ID (e.g., "module1", "tutorial-basics/create-a-page")
+ * @param pluginId - The docs plugin instance ID (default: "default")
+ * @returns Task statistics or null if doc not found or has no tasks
+ *
+ * @example
+ * const stats = useDocTaskStats("module1", "default");
+ * if (stats?.hasAnyTasks) {
+ *   return <Badge>{stats.completedTasks}/{stats.totalTasks}</Badge>;
+ * }
+ */
+export declare function useDocTaskStats(docId: string | undefined, pluginId?: string): DocTaskStats | null;
+/**
+ * Aggregate task statistics for multiple documents (e.g., category children)
+ *
+ * @param docIds - Array of document IDs
+ * @param pluginId - The docs plugin instance ID (default: "default")
+ * @param customProps - Optional customProps from sidebar item for badge configuration
+ * @returns Aggregated statistics or null if no tasks found
+ *
+ * @example
+ * const categoryStats = useCategoryTaskStats(
+ *   categoryItem.items.map(item => item.docId),
+ *   "default",
+ *   categoryItem.customProps
+ * );
+ */
+export declare function useCategoryTaskStats(docIds: (string | undefined)[], pluginId?: string, customProps?: Record<string, any>): Pick<DocTaskStats, "totalTasks" | "completedTasks" | "percentage" | "isComplete" | "hasAnyTasks" | "badgeConfig"> | null;
+//# sourceMappingURL=useDocTaskStats.d.ts.map

package/lib/utils/useDocTaskStats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocTaskStats.d.ts","sourceRoot":"","sources":["../../src/utils/useDocTaskStats.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAoB3D,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,cAAc,EAAE,OAAO,CAAC;IACxB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,UAAU,EAAE,OAAO,CAAC;IACpB,4CAA4C;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,QAAQ,GAAE,MAAkB,GAC3B,YAAY,GAAG,IAAI,CAsDrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,EAC9B,QAAQ,GAAE,MAAkB,EAC5B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAChC,IAAI,CACL,YAAY,EACV,YAAY,GACZ,gBAAgB,GAChB,YAAY,GACZ,YAAY,GACZ,aAAa,GACb,aAAa,CAChB,GAAG,IAAI,CAgIP"}

package/lib/utils/useDocTaskStats.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * Custom hook for getting task statistics for a specific document
+ * Combines data from task registry (metadata) and task context (completion states)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDocTaskStats = useDocTaskStats;
+exports.useCategoryTaskStats = useCategoryTaskStats;
+const react_1 = require("react");
+const TaskProvider_1 = require("../theme/TaskProvider");
+/**
+ * Safe version of useTaskContext that returns null if provider is not available
+ * This is needed for sidebar components that may render outside the TaskProvider
+ * (though after our fix, this should always have context available)
+ */
+function useSafeTaskContext() {
+    try {
+        return (0, TaskProvider_1.useTaskContext)();
+    }
+    catch (error) {
+        if (typeof window !== "undefined") {
+            console.warn("[Interactive Tasks] TaskContext not available in component. This may indicate a configuration issue.");
+        }
+        return null;
+    }
+}
+/**
+ * Get task statistics for a specific document
+ *
+ * @param docId - The document ID (e.g., "module1", "tutorial-basics/create-a-page")
+ * @param pluginId - The docs plugin instance ID (default: "default")
+ * @returns Task statistics or null if doc not found or has no tasks
+ *
+ * @example
+ * const stats = useDocTaskStats("module1", "default");
+ * if (stats?.hasAnyTasks) {
+ *   return <Badge>{stats.completedTasks}/{stats.totalTasks}</Badge>;
+ * }
+ */
+function useDocTaskStats(docId, pluginId = "default") {
+    const contextResult = useSafeTaskContext();
+    const { tasks, taskRegistry } = contextResult || {
+        tasks: {},
+        taskRegistry: null,
+    };
+    return (0, react_1.useMemo)(() => {
+        // Early returns inside useMemo are safe - they don't violate Rules of Hooks
+        // No context or no docId - return null
+        if (!contextResult || !docId) {
+            return null;
+        }
+        // Registry not loaded yet - return null
+        // This is expected during initial mount while registry loads
+        if (!taskRegistry) {
+            return null;
+        }
+        // Build the registry key: "pluginId/docId"
+        const docKey = `${pluginId}/${docId}`;
+        const docInfo = taskRegistry.docPages[docKey];
+        // Doc doesn't exist or has no tasks
+        if (!docInfo || docInfo.totalTasks === 0) {
+            return null;
+        }
+        // Count completed tasks
+        const taskKeys = Object.keys(docInfo.tasks);
+        const completedCount = taskKeys.filter((taskKey) => tasks[taskKey]?.completed).length;
+        const percentage = docInfo.totalTasks > 0
+            ? Math.round((completedCount / docInfo.totalTasks) * 100)
+            : 0;
+        return {
+            totalTasks: docInfo.totalTasks,
+            completedTasks: completedCount,
+            hasSectionName: docInfo.sectionName !== docInfo.title,
+            sectionName: docInfo.sectionName,
+            title: docInfo.title,
+            permalink: docInfo.permalink,
+            percentage,
+            isComplete: completedCount === docInfo.totalTasks,
+            hasAnyTasks: true,
+            badgeConfig: docInfo.badgeConfig,
+        };
+    }, [docId, pluginId, tasks, taskRegistry]);
+}
+/**
+ * Aggregate task statistics for multiple documents (e.g., category children)
+ *
+ * @param docIds - Array of document IDs
+ * @param pluginId - The docs plugin instance ID (default: "default")
+ * @param customProps - Optional customProps from sidebar item for badge configuration
+ * @returns Aggregated statistics or null if no tasks found
+ *
+ * @example
+ * const categoryStats = useCategoryTaskStats(
+ *   categoryItem.items.map(item => item.docId),
+ *   "default",
+ *   categoryItem.customProps
+ * );
+ */
+function useCategoryTaskStats(docIds, pluginId = "default", customProps) {
+    const contextResult = useSafeTaskContext();
+    const { tasks, taskRegistry } = contextResult || {
+        tasks: {},
+        taskRegistry: null,
+    };
+    return (0, react_1.useMemo)(() => {
+        // Early returns inside useMemo are safe
+        if (!taskRegistry || docIds.length === 0) {
+            return null;
+        }
+        // TODO: Remove after debugging - Log category stats calculation
+        console.log("[Interactive Tasks] useCategoryTaskStats called:", {
+            docIdsCount: docIds.length,
+            pluginId,
+            hasCustomProps: !!customProps,
+            customProps,
+        });
+        let totalTasks = 0;
+        let completedTasks = 0;
+        // Aggregate stats from all child docs
+        docIds.forEach((docId) => {
+            if (!docId)
+                return;
+            const docKey = `${pluginId}/${docId}`;
+            const docInfo = taskRegistry.docPages[docKey];
+            if (docInfo) {
+                totalTasks += docInfo.totalTasks;
+                // Count completed tasks for this doc
+                Object.keys(docInfo.tasks).forEach((taskKey) => {
+                    if (tasks[taskKey]?.completed) {
+                        completedTasks++;
+                    }
+                });
+            }
+        });
+        // No tasks found in any child
+        if (totalTasks === 0) {
+            // TODO: Remove after debugging
+            console.log("[Interactive Tasks] No tasks found in category children");
+            return null;
+        }
+        const percentage = Math.round((completedTasks / totalTasks) * 100);
+        // Extract badge config from customProps if provided
+        let badgeConfig;
+        if (customProps) {
+            const config = {};
+            let hasConfig = false;
+            if (customProps.sidebar_task_hide_progress !== undefined) {
+                config.hide = Boolean(customProps.sidebar_task_hide_progress);
+                hasConfig = true;
+            }
+            if (customProps.sidebar_task_disable_icon !== undefined) {
+                config.disableIcon = Boolean(customProps.sidebar_task_disable_icon);
+                hasConfig = true;
+            }
+            if (customProps.sidebar_task_badge_colors) {
+                const colors = customProps.sidebar_task_badge_colors;
+                config.colors = {};
+                if (colors.completed) {
+                    config.colors.completed = {
+                        lightmode: colors.completed.lightmode
+                            ? String(colors.completed.lightmode)
+                            : undefined,
+                        darkmode: colors.completed.darkmode
+                            ? String(colors.completed.darkmode)
+                            : undefined,
+                    };
+                    hasConfig = true;
+                }
+                if (colors.incomplete) {
+                    config.colors.incomplete = {
+                        lightmode: colors.incomplete.lightmode
+                            ? String(colors.incomplete.lightmode)
+                            : undefined,
+                        darkmode: colors.incomplete.darkmode
+                            ? String(colors.incomplete.darkmode)
+                            : undefined,
+                    };
+                    hasConfig = true;
+                }
+                if (colors.font) {
+                    config.colors.font = {
+                        lightmode: colors.font.lightmode
+                            ? String(colors.font.lightmode)
+                            : undefined,
+                        darkmode: colors.font.darkmode
+                            ? String(colors.font.darkmode)
+                            : undefined,
+                    };
+                    hasConfig = true;
+                }
+            }
+            badgeConfig = hasConfig ? config : undefined;
+            // TODO: Remove after debugging
+            console.log("[Interactive Tasks] Extracted badge config from customProps:", badgeConfig);
+        }
+        return {
+            totalTasks,
+            completedTasks,
+            percentage,
+            isComplete: completedTasks === totalTasks,
+            hasAnyTasks: true,
+            badgeConfig,
+        };
+    }, [docIds, pluginId, customProps, tasks, taskRegistry]);
+}
+//# sourceMappingURL=useDocTaskStats.js.map

package/lib/utils/useDocTaskStats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDocTaskStats.js","sourceRoot":"","sources":["../../src/utils/useDocTaskStats.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AA4DH,0CAyDC;AAiBD,oDA4IC;AAhRD,iCAAgC;AAChC,wDAAuD;AAGvD;;;;GAIG;AACH,SAAS,kBAAkB;IACzB,IAAI,CAAC;QACH,OAAO,IAAA,6BAAc,GAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CACV,sGAAsG,CACvG,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAyBD;;;;;;;;;;;;GAYG;AACH,SAAgB,eAAe,CAC7B,KAAyB,EACzB,WAAmB,SAAS;IAE5B,MAAM,aAAa,GAAG,kBAAkB,EAAE,CAAC;IAE3C,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,aAAa,IAAI;QAC/C,KAAK,EAAE,EAAE;QACT,YAAY,EAAE,IAAI;KACnB,CAAC;IAEF,OAAO,IAAA,eAAO,EAAC,GAAG,EAAE;QAClB,4EAA4E;QAE5E,uCAAuC;QACvC,IAAI,CAAC,aAAa,IAAI,CAAC,KAAK,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,wCAAwC;QACxC,6DAA6D;QAC7D,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,2CAA2C;QAC3C,MAAM,MAAM,GAAG,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAE9C,oCAAoC;QACpC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;YACzC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,wBAAwB;QACxB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC5C,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CACpC,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,SAAS,CACvC,CAAC,MAAM,CAAC;QACT,MAAM,UAAU,GACd,OAAO,CAAC,UAAU,GAAG,CAAC;YACpB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC;YACzD,CAAC,CAAC,CAAC,CAAC;QAER,OAAO;YACL,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,cAAc,EAAE,cAAc;YAC9B,cAAc,EAAE,OAAO,CAAC,WAAW,KAAK,OAAO,CAAC,KAAK;YACrD,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,UAAU;YACV,UAAU,EAAE,cAAc,KAAK,OAAO,CAAC,UAAU;YACjD,WAAW,EAAE,IAAI;YACjB,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC;IACJ,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,oBAAoB,CAClC,MAA8B,EAC9B,WAAmB,SAAS,EAC5B,WAAiC;IAUjC,MAAM,aAAa,GAAG,kBAAkB,EAAE,CAAC;IAE3C,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,aAAa,IAAI;QAC/C,KAAK,EAAE,EAAE;QACT,YAAY,EAAE,IAAI;KACnB,CAAC;IAEF,OAAO,IAAA,eAAO,EAAC,GAAG,EAAE;QAClB,wCAAwC;QACxC,IAAI,CAAC,YAAY,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzC,OAAO,IAAI,CAAC;QACd,CAAC;QAED,gEAAgE;QAChE,OAAO,CAAC,GAAG,CAAC,kDAAkD,EAAE;YAC9D,WAAW,EAAE,MAAM,CAAC,MAAM;YAC1B,QAAQ;YACR,cAAc,EAAE,CAAC,CAAC,WAAW;YAC7B,WAAW;SACZ,CAAC,CAAC;QAEH,IAAI,UAAU,GAAG,CAAC,CAAC;QACnB,IAAI,cAAc,GAAG,CAAC,CAAC;QAEvB,sCAAsC;QACtC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;YACvB,IAAI,CAAC,KAAK;gBAAE,OAAO;YAEnB,MAAM,MAAM,GAAG,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAC;YACtC,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAE9C,IAAI,OAAO,EAAE,CAAC;gBACZ,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC;gBAEjC,qCAAqC;gBACrC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;oBAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;wBAC9B,cAAc,EAAE,CAAC;oBACnB,CAAC;gBACH,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,8BAA8B;QAC9B,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;YACrB,+BAA+B;YAC/B,OAAO,CAAC,GAAG,CAAC,yDAAyD,CAAC,CAAC;YACvE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,cAAc,GAAG,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC;QAEnE,oDAAoD;QACpD,IAAI,WAAoC,CAAC;QACzC,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,MAAM,GAAgB,EAAE,CAAC;YAC/B,IAAI,SAAS,GAAG,KAAK,CAAC;YAEtB,IAAI,WAAW,CAAC,0BAA0B,KAAK,SAAS,EAAE,CAAC;gBACzD,MAAM,CAAC,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC;gBAC9D,SAAS,GAAG,IAAI,CAAC;YACnB,CAAC;YAED,IAAI,WAAW,CAAC,yBAAyB,KAAK,SAAS,EAAE,CAAC;gBACxD,MAAM,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,yBAAyB,CAAC,CAAC;gBACpE,SAAS,GAAG,IAAI,CAAC;YACnB,CAAC;YAED,IAAI,WAAW,CAAC,yBAAyB,EAAE,CAAC;gBAC1C,MAAM,MAAM,GAAG,WAAW,CAAC,yBAAyB,CAAC;gBACrD,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC;gBAEnB,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;oBACrB,MAAM,CAAC,MAAM,CAAC,SAAS,GAAG;wBACxB,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,SAAS;4BACnC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC;4BACpC,CAAC,CAAC,SAAS;wBACb,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ;4BACjC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC;4BACnC,CAAC,CAAC,SAAS;qBACd,CAAC;oBACF,SAAS,GAAG,IAAI,CAAC;gBACnB,CAAC;gBAED,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;oBACtB,MAAM,CAAC,MAAM,CAAC,UAAU,GAAG;wBACzB,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,SAAS;4BACpC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC;4BACrC,CAAC,CAAC,SAAS;wBACb,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,QAAQ;4BAClC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC;4BACpC,CAAC,CAAC,SAAS;qBACd,CAAC;oBACF,SAAS,GAAG,IAAI,CAAC;gBACnB,CAAC;gBAED,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;oBAChB,MAAM,CAAC,MAAM,CAAC,IAAI,GAAG;wBACnB,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS;4BAC9B,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;4BAC/B,CAAC,CAAC,SAAS;wBACb,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ;4BAC5B,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;4BAC9B,CAAC,CAAC,SAAS;qBACd,CAAC;oBACF,SAAS,GAAG,IAAI,CAAC;gBACnB,CAAC;YACH,CAAC;YAED,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;YAE7C,+BAA+B;YAC/B,OAAO,CAAC,GAAG,CACT,8DAA8D,EAC9D,WAAW,CACZ,CAAC;QACJ,CAAC;QAED,OAAO;YACL,UAAU;YACV,cAAc;YACd,UAAU;YACV,UAAU,EAAE,cAAc,KAAK,UAAU;YACzC,WAAW,EAAE,IAAI;YACjB,WAAW;SACZ,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/lib/utils/usePluginId.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Utility hook to reliably get the current plugin ID
+ * Uses Docusaurus internal APIs to determine which docs plugin instance
+ * the current page belongs to
+ */
+/**
+ * Get the plugin ID for the current documentation page
+ *
+ * This hook dynamically discovers all docs plugin instances and determines
+ * which one the current page belongs to by checking the active doc context.
+ *
+ * @param fallbackPluginId - Plugin ID to use if detection fails (default: 'default')
+ * @returns The detected plugin ID or the fallback
+ *
+ * @example
+ * ```tsx
+ * const pluginId = usePluginId();
+ * // On a page in the 'course' docs instance, returns 'course'
+ * // On a page in the 'resources' docs instance, returns 'resources'
+ * // Falls back to 'default' if cannot be determined
+ * ```
+ */
+export declare function usePluginId(fallbackPluginId?: string): string;
+//# sourceMappingURL=usePluginId.d.ts.map

package/lib/utils/usePluginId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePluginId.d.ts","sourceRoot":"","sources":["../../src/utils/usePluginId.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,gBAAgB,GAAE,MAAkB,GAAG,MAAM,CAoCxE"}

package/lib/utils/usePluginId.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Utility hook to reliably get the current plugin ID
+ * Uses Docusaurus internal APIs to determine which docs plugin instance
+ * the current page belongs to
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usePluginId = usePluginId;
+const client_1 = require("@docusaurus/plugin-content-docs/client");
+const useGlobalData_1 = require("@docusaurus/useGlobalData");
+/**
+ * Get the plugin ID for the current documentation page
+ *
+ * This hook dynamically discovers all docs plugin instances and determines
+ * which one the current page belongs to by checking the active doc context.
+ *
+ * @param fallbackPluginId - Plugin ID to use if detection fails (default: 'default')
+ * @returns The detected plugin ID or the fallback
+ *
+ * @example
+ * ```tsx
+ * const pluginId = usePluginId();
+ * // On a page in the 'course' docs instance, returns 'course'
+ * // On a page in the 'resources' docs instance, returns 'resources'
+ * // Falls back to 'default' if cannot be determined
+ * ```
+ */
+function usePluginId(fallbackPluginId = "default") {
+    try {
+        // Get all instances of the docs plugin
+        const allDocsData = (0, useGlobalData_1.useAllPluginInstancesData)("docusaurus-plugin-content-docs");
+        // Extract plugin IDs from the global data
+        const pluginIds = Object.keys(allDocsData || {});
+        // If no plugin instances found, use fallback
+        if (pluginIds.length === 0) {
+            return fallbackPluginId;
+        }
+        // Try each plugin instance to find which one has the active doc
+        for (const id of pluginIds) {
+            try {
+                const context = (0, client_1.useActiveDocContext)(id);
+                // If this context has an active doc, this is our plugin
+                if (context?.activeDoc) {
+                    return id;
+                }
+            }
+            catch (e) {
+                // This plugin instance doesn't have an active doc, continue
+                continue;
+            }
+        }
+        // If no active context found, use fallback
+        return fallbackPluginId;
+    }
+    catch (e) {
+        // If hook isn't available (shouldn't happen), use fallback
+        console.warn("[Interactive Tasks] Failed to detect pluginId:", e);
+        return fallbackPluginId;
+    }
+}
+//# sourceMappingURL=usePluginId.js.map

package/lib/utils/usePluginId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePluginId.js","sourceRoot":"","sources":["../../src/utils/usePluginId.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAsBH,kCAoCC;AAxDD,mEAA6E;AAC7E,6DAAsE;AAEtE;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,WAAW,CAAC,mBAA2B,SAAS;IAC9D,IAAI,CAAC;QACH,uCAAuC;QACvC,MAAM,WAAW,GAAG,IAAA,yCAAyB,EAC3C,gCAAgC,CACjC,CAAC;QAEF,0CAA0C;QAC1C,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;QAEjD,6CAA6C;QAC7C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,gBAAgB,CAAC;QAC1B,CAAC;QAED,gEAAgE;QAChE,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,IAAA,4BAAmB,EAAC,EAAE,CAAC,CAAC;gBACxC,wDAAwD;gBACxD,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC;oBACvB,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,4DAA4D;gBAC5D,SAAS;YACX,CAAC;QACH,CAAC;QAED,2CAA2C;QAC3C,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,2DAA2D;QAC3D,OAAO,CAAC,IAAI,CAAC,gDAAgD,EAAE,CAAC,CAAC,CAAC;QAClE,OAAO,gBAAgB,CAAC;IAC1B,CAAC;AACH,CAAC"}