@sp-days-framework/docusaurus-plugin-interactive-tasks 1.0.5-rc2 → 1.1.0-beta2

package/docs/advanced-configuration.mdx

@@ -0,0 +1,275 @@
+---
+sidebar_position: 1.2
+sidebar_custom_props:
+  section: "Setup"
+  section_position: 1
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Advanced Configuration
+
+## TOC (Table of Contents) Configuration
+
+The Interactive Tasks plugin supports TOC configuration via the `remarkTaskDirective` plugin options. This allows you to control whether tasks appear in the table of contents and at what heading level.
+
+### Remark Plugin Options
+
+Configure TOC behavior in your `docusaurus.config.ts` for each docs instance:
+
+```ts title="docusaurus.config.ts"
+module.exports = {
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          beforeDefaultRemarkPlugins: [
+            [
+              require('@sp-days-framework/docusaurus-plugin-interactive-tasks')
+                .remarkTaskDirective,
+              {
+                // Enable TOC generation for tasks (default: true)
+                tocEnabled: true,
+                
+                // Heading level for TOC entries (default: 2)
+                // Values: 2 (h2), 3 (h3), 4 (h4), 5 (h5), 6 (h6)
+                tocHeadingLevel: 2,
+              },
+            ],
+          ],
+        },
+      },
+    ],
+  ],
+};
+```
+
+### Remark Plugin Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `tocEnabled` | `boolean` | `true` | Enable/disable TOC entry generation for tasks |
+| `tocHeadingLevel` | `2` \| `3` \| `4` \| `5` \| `6` | `2` | Heading level for TOC entries (h2-h6) |
+
+### TOC Configuration Examples
+
+#### Disable TOC Generation
+
+If you don't want tasks to appear in the table of contents:
+
+```ts title="docusaurus.config.ts"
+beforeDefaultRemarkPlugins: [
+  [
+    require('@sp-days-framework/docusaurus-plugin-interactive-tasks')
+      .remarkTaskDirective,
+    {
+      tocEnabled: false,
+    },
+  ],
+],
+```
+
+#### Use h3 for Task TOC Entries
+
+To make tasks appear as subsections in the TOC:
+
+```ts title="docusaurus.config.ts"
+beforeDefaultRemarkPlugins: [
+  [
+    require('@sp-days-framework/docusaurus-plugin-interactive-tasks')
+      .remarkTaskDirective,
+    {
+      tocEnabled: true,
+      tocHeadingLevel: 3, // Tasks appear as h3 in TOC
+    },
+  ],
+],
+```
+
+This is useful when you have main h2 headings and want tasks to be nested under them in the TOC.
+
+#### Different Config Per Docs Instance
+
+You can configure TOC differently for each docs instance:
+
+```ts title="docusaurus.config.ts"
+module.exports = {
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          // Course docs: use h2 for tasks
+          beforeDefaultRemarkPlugins: [
+            [
+              require('@sp-days-framework/docusaurus-plugin-interactive-tasks')
+                .remarkTaskDirective,
+              { tocEnabled: true, tocHeadingLevel: 2 },
+            ],
+          ],
+        },
+      },
+    ],
+  ],
+  plugins: [
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        id: 'resources',
+        path: 'resources',
+        // Resources docs: use h3 for tasks
+        beforeDefaultRemarkPlugins: [
+          [
+            require('@sp-days-framework/docusaurus-plugin-interactive-tasks')
+              .remarkTaskDirective,
+            { tocEnabled: true, tocHeadingLevel: 3 },
+          ],
+        ],
+      },
+    ],
+  ],
+};
+```
+
+## Document Frontmatter Options
+
+| Property                        | Type      | Default | Description                                        |
+| ------------------------------- | --------- | ------- | -------------------------------------------------- |
+| `sidebar_task_hide_progress`    | `boolean` | `false` | Hide the task progress badge entirely              |
+| `sidebar_task_disable_icon`     | `boolean` | `false` | Show "5/5" instead of checkmark icon when complete |
+| `sidebar_task_badge_colors`     | `object`  | -       | Badge color configuration (see below)              |
+
+### Badge Colors Structure
+
+```yaml
+sidebar_task_badge_colors:
+  completed:
+    lightmode: "#4caf50"  # Background color when all tasks completed (light mode)
+    darkmode: "#66bb6a"   # Background color when all tasks completed (dark mode)
+  incomplete:
+    lightmode: "#2196f3"  # Background color when tasks incomplete (light mode)
+    darkmode: "#42a5f5"   # Background color when tasks incomplete (dark mode)
+  font:
+    lightmode: "#ffffff"  # Text color (light mode)
+    darkmode: "#000000"   # Text color (dark mode)
+```
+
+**Supported Color Formats:**
+
+- Hex: `#ff6b6b`, `#f00`
+- RGB/RGBA: `rgb(255, 107, 107)`, `rgba(255, 107, 107, 0.8)`
+- HSL/HSLA: `hsl(0, 100%, 71%)`
+- Named colors: `red`, `blue`, `green`
+- CSS variables: `var(--ifm-color-primary)`
+
+## How It Works
+
+### Task Registry
+
+During the build process, the plugin:
+
+1. **Scans** all MDX files in the docs directory for task directives
+2. **Extracts** metadata from each task (name, number, document info)
+3. **Reads** frontmatter for document-level badge customization
+4. **Generates** a registry file (`task-registry.json`) containing:
+   - Total task count per document
+   - Task names and sequential numbers
+   - Document metadata (title, section, permalink)
+   - Badge customization settings from frontmatter
+   - Sidebar position information
+
+The registry powers features like the TaskProgression component and sidebar badges.
+
+### Completion Tracking
+
+Task completion is tracked using browser localStorage:
+
+- **Storage Keys** - Format: `task-{pluginId}-{docId}-{taskNumber}-{encodedName}`
+- **Real-time Updates** - Progress updates immediately when tasks are completed
+- **Cross-tab Sync** - Changes sync across browser tabs via storage events
+- **Persistence** - Completion state persists across browser sessions
+
+### Path Resolution
+
+The TaskProgression component uses intelligent path resolution:
+
+1. **Normalizes** the provided path (handles `@site/` prefix, file extensions)
+2. **Resolves** relative paths (`.`, `./`, `../`) based on current document
+3. **Searches** the task registry for matching document source
+4. **Returns** document metadata and task information
+
+This allows flexible path references:
+
+```mdx
+<!-- Absolute paths -->
+<TaskProgression path="/docs/module1/tasks" />
+
+<!-- Relative paths -->
+<TaskProgression path="./sibling-page" />
+<TaskProgression path="../parent-page" />
+
+<!-- Current page -->
+<TaskProgression path="." />
+```
+
+## Multiple Docs Instances
+
+The plugin automatically works with [multiple docs instances](https://docusaurus.io/docs/docs-multi-instance). Each instance is tracked independently:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          path: 'docs',
+          remarkPlugins: [
+            require('@sp-days-framework/docusaurus-plugin-interactive-tasks').remarkTaskDirective,
+          ],
+        },
+      },
+    ],
+  ],
+  plugins: [
+    '@sp-days-framework/docusaurus-plugin-interactive-tasks',
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        id: 'community',
+        path: 'community',
+        routeBasePath: 'community',
+        remarkPlugins: [
+          require('@sp-days-framework/docusaurus-plugin-interactive-tasks').remarkTaskDirective,
+        ],
+      },
+    ],
+  ],
+};
+```
+
+The `TaskProgression` component auto-detects the instance. To reference a different instance explicitly:
+
+```mdx
+<!-- Auto-detects parent doc's instance -->
+<TaskProgression path="./intro" />
+
+<!-- Explicitly reference a different instance -->
+<TaskProgression path="/docs/intro" pluginId="default" />
+<TaskProgression path="/community/getting-started" pluginId="community" />
+```
+
+### Configuring `TaskProgression`
+
+| Prop       | Type     | Default     | Description                                    |
+| ---------- | -------- | ----------- | ---------------------------------------------- |
+| `path`     | `string` | **Required** | Path to the document (absolute or relative)   |
+| `pluginId` | `string` | *Auto-detected* | [Docs Multi-instance](https://docusaurus.io/docs/docs-multi-instance) instance ID. Auto-detects from parent doc if not provided. |
+
+### Configuring `TaskProgressionOverview`
+
+| Prop       | Type     | Default     | Description                  |
+| ---------- | -------- | ----------- | ---------------------------- |
+| `pluginId` | `string` | *Auto-detected* | [Docs Multi-instance](https://docusaurus.io/docs/docs-multi-instance) instance ID. Auto-detects from parent doc if not provided. |

package/docs/changelog.mdx

@@ -0,0 +1,192 @@
+---
+toc_max_heading_level: 2
+sidebar_position: 4.1
+sidebar_label: "Change Logs"
+sidebar_custom_props:
+  section: "Releases"
+  section_position: 4
+---
+
+# Changelog
+
+## `@sp-days-framework/docusaurus-plugin-interactive-tasks`
+
+[![npm version](https://img.shields.io/npm/v/@sp-days-framework/docusaurus-plugin-interactive-tasks?logo=nodedotjs)](https://www.npmjs.com/package/@sp-days-framework/docusaurus-plugin-interactive-tasks)
+
+:::note
+All packages within `@sp-days-framework` use the same version number. In some cases, a package might just be "bumped" to match the rest without any functional changes.
+:::
+
+---
+
+## Version 1.1.0-beta2 ![beta](https://img.shields.io/badge/release-beta-yellow)
+
+Enhanced documentation with practical examples
+
+<details>
+<summary><strong>Beta Details</strong> (2025 December 09)</summary>
+
+### Improvements
+
+- **Better Documentation**: Added new task examples with detailed output explanations
+  - Clearer demonstrations of plugin capabilities
+  - More practical usage examples for common scenarios
+- **Improved Structure**: Updated sidebar positions and added known issues documentation
+- **Visual Refinements**: Enhanced sidebar and navbar logo handling
+
+</details>
+
+---
+
+## Version 1.1.0-beta1 ![beta](https://img.shields.io/badge/release-beta-yellow)
+
+Show expected outputs and enjoy smoother interactions
+
+<details>
+<summary><strong>Beta Details</strong> (2025 December 08)</summary>
+
+### New Features
+
+- **Output Display**: Show learners what to expect when completing tasks
+  - New `:::output` directive displays expected command results or task outcomes
+  - Helps learners verify they're on the right track
+  - Consistent styling with hints and solutions
+
+- **Better Navigation**: Tasks now appear in your page's table of contents
+  - Easier to jump between tasks in long tutorials
+  - Improved document structure for better accessibility
+
+### Improvements
+
+- **Smoother Animations**: Polished panel transitions when revealing hints, solutions, and outputs
+  - No more jarring layout shifts
+  - More responsive and professional feel
+
+### Bug Fixes
+
+- Fixed compatibility issues with Docusaurus's markdown processing pipeline
+
+### Package Documentation
+
+- Documentation is now bundled with the npm package, making it accessible during development and for offline reference
+
+</details>
+
+---
+
+## Version 1.0.4 ![Release](https://img.shields.io/badge/release-production-blue)
+
+TOC support and animation improvements
+
+<details>
+<summary><strong>Details</strong> (2025 December 1)</summary>
+
+### New Features
+
+- Added TOC support for Task Component
+
+### Improvements
+
+- Refactor Task Component animation for smoother transitions
+
+### Migration Guide
+
+Users will need to update their Docusaurus config file to use `beforeDefaultRemarkPlugins` instead of `remarkPlugins`
+
+**Examples:**
+
+```js title="/src/components/HelloCodeTitle.js"
+presets: [
+[
+    "classic",
+    {
+    docs: {
+        id: "course",
+        path: "course",
+        routeBasePath: "course",
+        beforeDefaultRemarkPlugins: [
+        require("@sp-days-framework/docusaurus-plugin-interactive-tasks")
+            .remarkTaskDirective,
+        ],
+...
+"@docusaurus/plugin-content-docs",
+{
+id: "resources",
+path: "resources",
+routeBasePath: "resources",
+beforeDefaultRemarkPlugins: [
+    [
+    require('@sp-days-framework/docusaurus-plugin-interactive-tasks')
+        .remarkTaskDirective,
+    {
+        // TOC configuration for resources docs instance
+        tocEnabled: true,
+        tocHeadingLevel: 3, // Use h2 for TOC entries (can be 2-6)
+    },
+],
+
+```
+
+</details>
+
+---
+
+## Version 1.0.3 ![Release](https://img.shields.io/badge/release-production-blue)
+
+Component styling improvements
+
+<details>
+<summary><strong>Details</strong> (2025 November 27)</summary>
+
+### Bug Fixes
+
+- Fix Task component styling
+
+</details>
+
+---
+
+## Version 1.0.2 ![Release](https://img.shields.io/badge/release-production-blue)
+
+Fix for broken anchors
+
+<details>
+<summary><strong>Details</strong> (2025 November 25)</summary>
+
+### Bug Fixes
+
+- Resolve broken anchors by swizzling Layout instead of Root
+- Removed swizzle of DocRoot and Root components to prevent interference with Docusaurus's SSG anchor collection
+- Introduced a new Layout component to provide TaskProvider and DocTaskCounterProvider without breaking the component chain
+
+</details>
+
+---
+
+## Version 1.0.1 ![Sync](https://img.shields.io/badge/sync-version--bump-lightgrey)
+
+Code cleanup
+
+<details>
+<summary><strong>Details</strong> (2025 November 25)</summary>
+
+### Improvements
+
+- Cleaned up MDXComponents to avoid direct imports that bypass theme resolution
+
+</details>
+
+---
+
+## Version 1.0.0 ![Release](https://img.shields.io/badge/release-production-blue)
+
+Initial release of the Interactive Tasks plugin
+
+<details>
+<summary><strong>Details</strong> (2025 November 24)</summary>
+
+### New Features
+
+- Initial release with interactive task tracking functionality
+
+</details>