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

package/docs/example-advanced-usage.mdx

@@ -0,0 +1,308 @@
+---
+task_section_name: "Interactive Demo 2"
+sidebar_position: 3.2
+sidebar_label: "Advanced Usage"
+sidebar_custom_props:
+  section: "Examples"
+  section_position: 3
+---
+
+import { useState } from 'react';
+
+# Advanced Usage Example
+
+Discover how to leverage advanced Docusaurus markdown features within interactive tasks to create rich, engaging learning experiences.
+
+<TaskProgression path="." />
+
+---
+
+::::task[Add Syntax Highlighting to Code Blocks]
+
+Practice adding syntax-highlighted code blocks to your documentation:
+
+1. Create a code block using triple backticks (```)
+2. Add the language identifier immediately after the opening backticks
+3. Write your code inside the block
+4. Close with triple backticks
+
+**Bash example:**
+```bash
+docker run -d -p 8080:80 nginx
+npm install express
+```
+
+**YAML example:**
+```yaml
+version: '3.8'
+services:
+  web:
+    image: nginx:latest
+    ports:
+      - "8080:80"
+```
+
+**JSON example:**
+```json
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "dependencies": {
+    "react": "^18.0.0"
+  }
+}
+```
+
+:::hint
+Docusaurus supports 30+ languages out of the box. Check the [Prism language list](https://prismjs.com/#supported-languages) for all available options. You can add more languages in `docusaurus.config.ts` - see the [Docusaurus documentation](https://docusaurus.io/docs/markdown-features/code-blocks#supported-languages).
+:::
+
+::::
+
+---
+
+::::task[Add File Names to Code Blocks]
+
+Add descriptive file names to your code blocks for better context:
+
+1. After the language identifier, add a space and `title="filename.ext"`
+2. The filename will appear as a header above the code block
+3. This helps readers know exactly where code should be placed
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "strict": true,
+    "strictNullChecks": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+:::hint
+Use this feature to show exactly where code should be placed in a project structure. It's especially helpful in tutorials with multiple files.
+:::
+
+::::
+
+---
+
+::::task[Highlight Important Code Lines]
+
+Learn two methods for highlighting specific lines in code blocks:
+
+**Method 1: Inline comments** (best when actively developing)
+
+Use `highlight-next-line`, `highlight-start`, and `highlight-end` comments to mark important lines:
+
+```js
+function HighlightSomeText(highlight) {
+  if (highlight) {
+    // highlight-next-line
+    return 'This text is highlighted!';
+  }
+
+  return 'Nothing highlighted';
+}
+
+function HighlightMoreText(highlight) {
+  // highlight-start
+  if (highlight) {
+    return 'This range is highlighted!';
+  }
+  // highlight-end
+
+  return 'Nothing highlighted';
+}
+```
+
+**Method 2: Meta string** (cleaner for published docs)
+
+Add line numbers after the language identifier. Separate multiple lines with commas or use ranges:
+
+```jsx {1,4-6,11}
+import React from 'react';
+
+function MyComponent(props) {
+  if (props.isBar) {
+    return <div>Bar</div>;
+  }
+
+  return <div>Foo</div>;
+}
+
+export default MyComponent;
+```
+
+:::hint
+
+Supported commenting syntax:
+
+| Style      | Syntax                   |
+| ---------- | ------------------------ |
+| C-style    | `/* ... */` and `// ...` |
+| JSX-style  | `{/* ... */}`            |
+| Bash-style | `# ...`                  |
+| HTML-style | `<!-- ... -->`           |
+
+Choose inline comments when actively developing, and meta strings for final published documentation.
+
+:::
+
+::::
+
+---
+
+:::::task[Nest Admonitions in Tasks]
+
+Practice nesting admonitions inside tasks by using the correct number of colons:
+
+1. Task containers use 4+ colons: `::::task`
+2. Hints/solutions use 3+ colons: `:::hint`
+3. Nested admonitions also use 3+ colons: `:::note`
+4. For deeper nesting inside hints/solutions, use 4+ colons for the admonition
+
+**Rule:** Parent containers always need **more colons** than their children to prevent the parser from prematurely closing containers.
+
+:::note
+
+This is a note at the task level (3 colons).
+
+:::
+
+:::warning
+
+This is a warning at the task level (3 colons).
+
+:::
+
+::::hint
+
+This hint contains a nested admonition (4 colons for hint, since it needs to contain a 3-colon admonition):
+
+:::note
+
+This note is nested inside the hint (3 colons).
+
+:::
+
+::::
+
+:::::
+
+---
+
+::::task[Use React Components in Tasks]
+
+Import and use React components within your task content to create interactive experiences:
+
+1. Import React and any hooks you need at the top of the file: `import { useState } from 'react';`
+2. Define your component using `export const`
+3. Use the component anywhere in your MDX content
+
+**Example - Interactive Counter:**
+
+export const Counter = () => {
+  const [count, setCount] = useState(0);
+  return (
+    <div style={{ 
+      padding: '1rem', 
+      border: '2px solid var(--ifm-color-primary)', 
+      borderRadius: '8px',
+      textAlign: 'center',
+      margin: '1rem 0'
+    }}>
+      <p style={{ fontSize: '1.5rem', margin: '0.5rem 0' }}>
+        Count: <strong>{count}</strong>
+      </p>
+      <button 
+        onClick={() => setCount(count + 1)}
+        style={{ 
+          marginRight: '0.5rem',
+          padding: '0.5rem 1rem',
+          fontSize: '1rem',
+          cursor: 'pointer'
+        }}
+      >
+        Increment
+      </button>
+      <button 
+        onClick={() => setCount(0)}
+        style={{ 
+          padding: '0.5rem 1rem',
+          fontSize: '1rem',
+          cursor: 'pointer'
+        }}
+      >
+        Reset
+      </button>
+    </div>
+  );
+};
+
+<Counter />
+
+:::hint
+
+Tasks support all Docusaurus MDX features, including:
+- React component imports and usage (useState, useEffect, etc.)
+- Tabs, admonitions, and other built-in components
+- Custom CSS and styling with theme-aware variables
+- Interactive JavaScript functionality
+
+This makes tasks perfect for interactive tutorials and hands-on learning experiences!
+
+:::
+
+:::solution
+
+Here is the React code running in the task:
+
+```ts
+import { useState } from 'react';
+
+export const Counter = () => {
+  const [count, setCount] = useState(0);
+  return (
+    <div style={{ 
+      padding: '1rem', 
+      border: '2px solid var(--ifm-color-primary)', 
+      borderRadius: '8px',
+      textAlign: 'center',
+      margin: '1rem 0'
+    }}>
+      <p style={{ fontSize: '1.5rem', margin: '0.5rem 0' }}>
+        Count: <strong>{count}</strong>
+      </p>
+      <button 
+        onClick={() => setCount(count + 1)}
+        style={{ 
+          marginRight: '0.5rem',
+          padding: '0.5rem 1rem',
+          fontSize: '1rem',
+          cursor: 'pointer'
+        }}
+      >
+        Increment
+      </button>
+      <button 
+        onClick={() => setCount(0)}
+        style={{ 
+          padding: '0.5rem 1rem',
+          fontSize: '1rem',
+          cursor: 'pointer'
+        }}
+      >
+        Reset
+      </button>
+    </div>
+  );
+};
+
+<Counter />
+```
+
+:::
+
+::::

package/docs/example-basic-usage.mdx

@@ -0,0 +1,132 @@
+---
+task_section_name: "Interactive Demo 1"
+sidebar_position: 3.1
+sidebar_label: "Basic Usage"
+sidebar_custom_props:
+  section: "Examples"
+  section_position: 3
+---
+
+# Basic Usage Example
+
+See interactive tasks in action with real-world examples. This page demonstrates how tasks work in a documentation environment.
+
+<TaskProgression path="."/>
+
+---
+
+::::task[Install the Plugin]
+
+Follow these steps to add Interactive Tasks to your Docusaurus project:
+
+1. Open your terminal in the project root directory
+2. Run the installation command for your package manager
+3. Verify the package appears in your `package.json` dependencies
+
+
+:::hint
+
+If you created your project with `@sp-days-framework/create-sp-days`, this plugin is already installed and you can skip this task.
+
+:::
+
+::::
+
+---
+
+::::task[Configure Docusaurus]
+
+Add the plugin and remark plugin to your Docusaurus configuration:
+
+1. Open `docusaurus.config.js` in your project root
+2. Add the plugin to the `plugins` array
+3. Add the remark plugin to your preset's docs configuration
+4. Save the file
+
+:::solution
+
+The plugin needs to be registered in two places: the `plugins` array for the main functionality, and the `remarkPlugins` array to transform task directives in your markdown files.
+
+**Verify Configuration:**
+
+- The file should have both entries as shown below
+- No syntax errors when running `npm run start`
+
+Add to your `docusaurus.config.js`:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: ["@sp-days-framework/docusaurus-plugin-interactive-tasks"],
+
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          remarkPlugins: [
+            require("@sp-days-framework/docusaurus-plugin-interactive-tasks")
+              .remarkTaskDirective,
+          ],
+        },
+      },
+    ],
+  ],
+};
+```
+
+:::
+
+::::
+
+---
+
+::::task[Add Progress Tracking]
+
+Display task completion progress on your documentation pages:
+
+1. Import the `TaskProgression` component in your MDX file
+2. Add the component where you want to show progress
+3. Provide the path to the document you want to track
+
+Add to your MDX file:
+
+```mdx
+import TaskProgression from "@theme/TaskProgression";
+
+<TaskProgression path="." />
+```
+
+Reference other pages:
+
+```mdx
+<TaskProgression path="/docs/tutorial/first-task" />
+<TaskProgression path="../module-02/introduction" />
+```
+
+:::hint
+
+Use `path="."` to reference the current page, or provide an absolute/relative path to track other pages. The component shows a visual progress bar and completion count.
+
+:::
+
+::::
+
+---
+
+::::task[Test Auto-Collapse Feature]
+
+Learn how the auto-collapse feature helps you focus on incomplete tasks:
+
+1. Complete at least one task on this page by clicking "Mark as Done"
+2. Look for the collapse icon button in the navbar
+3. Click the collapse icon to enable auto-collapse mode
+4. Observe how completed tasks automatically collapse
+5. Click the collapse icon again to disable the feature
+
+:::hint
+
+The auto-collapse setting is saved to your browser's localStorage and syncs across all tabs. This feature is especially useful when working through long tutorial pages with many tasks.
+
+:::
+
+::::

package/docs/index.mdx

@@ -0,0 +1,159 @@
+---
+title: Interactive Tasks
+hide_title: true
+sidebar_class_name: title-logo-sidebar-docusaurus
+sidebar_label: "Interactive Tasks"
+sidebar_position: 0
+---
+
+import LogoDocusaurus from './logo-docusaurus.svg';
+
+<div align="center">
+  <div style={{ display: 'flex', justifyContent: 'center', margin: '1rem' }}>
+    <LogoDocusaurus width="110" height="110"/>
+  </div>
+  <div align="center">
+    # Interactive Tasks
+  </div>
+  <div align="center">
+    <p>
+      *A Docusaurus plugin that transforms documentation into interactive learning experiences!*
+    </p>
+    <h4>
+      <a href="./interactive-tasks/install">🔧 Setup</a> · 
+      <a href="https://www.npmjs.com/package/@sp-days-framework/docusaurus-plugin-interactive-tasks">📦 NPM Package</a> · 
+      <a href="https://github.com/helse-sorost/sp-days-framework">💻 Source Code</a>
+    </h4>
+  </div>
+</div>
+
+<div style={{ position: 'relative', marginTop: '2rem', display: 'flex', justifyContent: 'center' }}>
+  <div style={{ position: 'absolute', left: '50%', marginTop: '4px', transform: 'translateX(-50%)', fontWeight: 500, color: 'var(--ifm-color-emphasis-600)' }}>
+    Preview
+  </div>
+  <div id="preview-task-example" style={{ borderRadius: '12px', padding: '2rem 1.7rem 0rem', background: 'var(--ifm-color-emphasis-200)' }}>
+    <style>{`
+      #preview-task-example h3 {
+        display: none !important;
+      }
+    `}</style>
+    ::::task-example[Calibrate the Flux Capacitor ⚡]
+
+    Great Scott, Marty! We need to recalibrate the **temporal documentation flux capacitor** to 1.21 gigawatts! 
+    
+    1. Check the chronosync matrix for para-dimensional efficiency
+    2. Initiate the **quantum state persistence protocol**
+    3. Engage the localStorage temporal buffer
+    4. Restart the cross-timeline synchronization array by running the following command:
+      ```bash
+      sudo systemctl restart ntpd
+      ```
+
+    :::hint
+    The "Mark as Done" actuator button is located in the down-right quadrant of the task containment field. A simple click should energize the completion state capacitor!
+    :::
+
+    :::output
+    If done correctly, you should observe the following temporal anomalies:
+    
+    ```
+    ⚡ Flux capacitor status: ENGAGED
+    📊 Temporal progress vector: SYNCHRONIZED
+    💾 localStorage quantum buffer: PERSISTED
+    ✅ Task completion waveform: COLLAPSED TO TRUE STATE
+    ```
+
+    Heavy! Your progress just traveled through time! 🚗💨
+    :::
+
+    :::solution
+    When you check that box, the plugin harnesses the power of localStorage to preserve your completion state across multiple timeline iterations (browser sessions). 
+    
+    The temporal data persists even if you reload the page or jump to a different tab - it's like the DeLorean maintaining 88 mph across different roads! 
+    
+    Key features of the completion tracking system:
+    - **Persistent storage** across browser sessions
+    - **Real-time synchronization** between tabs
+    - **Automatic state management** for your learning progress
+    - **Cross-dimensional compatibility** (works in any timeline!)
+    
+    *This is heavy... but in a good way!* 🎸
+    :::
+
+    ::::
+  </div>
+</div>
+<br/>
+
+---
+
+## Features
+
+- **Interactive Tasks** - Collapsible task components with completion tracking
+- **Hints, Solutions & Expected Outputs** - Optional toggleable hints, solutions, and expected outputs for each task
+- **Auto-Numbering** - Automatic task numbering per page
+- **Persistent Progress** - Completion status saved to localStorage
+- **Progress Tracking** - Visual progress indicators in sidebar and task progression components
+- **Sidebar Badges** - Automatic completion badges (e.g., "2/5") in sidebar navigation
+- **Auto-Collapse Toggle** - Navbar button to enable/disable auto-collapsing of completed tasks
+
+## Getting Started
+
+Create interactive tasks using simple markdown directives:
+
+````mdx
+::::task[Install the Plugin]
+
+Install the Interactive Tasks plugin using npm or yarn.
+
+:::hint
+Use npm install or yarn add to install the package.
+:::
+
+:::output
+You should see output similar to:
+
+```
+added 1 package, and audited 2 packages in 3s
+
+found 0 vulnerabilities
+```
+:::
+
+:::solution
+```bash
+npm install @sp-days-framework/docusaurus-plugin-interactive-tasks
+```
+:::
+
+::::
+````
+
+::::task-example[Install the Plugin]
+
+Install the Interactive Tasks plugin using npm or yarn.
+
+:::hint
+Use npm install or yarn add to install the package.
+:::
+
+:::output
+You should see output similar to:
+
+```
+added 1 package, and audited 2 packages in 3s
+
+found 0 vulnerabilities
+```
+:::
+
+:::solution
+```bash
+npm install @sp-days-framework/docusaurus-plugin-interactive-tasks
+```
+:::
+
+::::
+
+
+Tasks are automatically numbered, track completion in localStorage, and sync across browser tabs. See [Install](install.mdx) for installation and configuration.

package/docs/install.mdx

@@ -0,0 +1,121 @@
+---
+sidebar_position: 1.1
+sidebar_custom_props:
+  section: "Setup"
+  section_position: 1
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Installation
+
+:::tip[Already Included]
+If you're using `@sp-days-framework/create-sp-days`, the Interactive Tasks plugin is already installed and configured. You can start creating tasks right away!
+:::
+
+Install the plugin using your preferred package manager:
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm install @sp-days-framework/docusaurus-plugin-interactive-tasks
+    ```
+  </TabItem>
+  <TabItem value="yarn" label="Yarn">
+    ```bash
+    yarn add @sp-days-framework/docusaurus-plugin-interactive-tasks
+    ```
+  </TabItem>
+</Tabs>
+
+Add the plugin to your plugins array and the remark plugin to your docs configuration:
+
+```js title="docusaurus.config.js" {2,9-11}
+module.exports = {
+  plugins: ["@sp-days-framework/docusaurus-plugin-interactive-tasks"],
+
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          beforeDefaultRemarkPlugins: [
+            require("@sp-days-framework/docusaurus-plugin-interactive-tasks")
+              .remarkTaskDirective,
+          ],
+        },
+      },
+    ],
+  ],
+};
+```
+
+### Frontmatter Options
+
+Customize task badge appearance for individual pages:
+
+```mdx title="docs/my-module.mdx"
+---
+title: My Module
+sidebar_task_hide_progress: false
+sidebar_task_disable_icon: false
+sidebar_task_badge_colors:
+  completed:
+    lightmode: "#4caf50"
+    darkmode: "#66bb6a"
+  incomplete:
+    lightmode: "#2196f3"
+    darkmode: "#42a5f5"
+  font:
+    lightmode: "#ffffff"
+    darkmode: "#000000"
+---
+
+# My Module Content
+```
+
+### Category Sidebar Configuration
+
+Customize task badges for entire categories using `_category_.yml` or `_category_.json`:
+
+<Tabs>
+  <TabItem value="yaml" label="YAML" default>
+    ```yaml title="docs/module-01/_category_.yml"
+    label: "Module 1"
+    position: 1
+    customProps:
+      sidebar_task_badge_colors:
+        completed:
+          lightmode: "#4caf50"
+          darkmode: "#66bb6a"
+        incomplete:
+          lightmode: "#2196f3"
+          darkmode: "#42a5f5"
+      sidebar_task_disable_icon: false
+    ```
+  </TabItem>
+  <TabItem value="json" label="JSON">
+    ```json title="docs/module-02/_category_.json"
+    {
+      "label": "Module 2",
+      "position": 2,
+      "customProps": {
+        "sidebar_task_hide_progress": false,
+        "sidebar_task_badge_colors": {
+          "completed": {
+            "lightmode": "#4caf50",
+            "darkmode": "#66bb6a"
+          },
+          "incomplete": {
+            "lightmode": "#2196f3",
+            "darkmode": "#42a5f5"
+          }
+        }
+      }
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+See [Advanced Configuration](./advanced-configuration.mdx) for all available options.