@sp-days-framework/create-sp-days 1.0.0

package/templates/addon-resources/resources/interactive-tasks/examples/advanced-usage.mdx

@@ -0,0 +1,304 @@
+---
+sidebar_position: 2
+task_section_name: "Demo Module 2"
+---
+
+import { useState } from 'react';
+
+# Advanced Task Page
+
+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/templates/addon-resources/resources/interactive-tasks/examples/basic-usage.mdx

@@ -0,0 +1,128 @@
+---
+sidebar_position: 1
+task_section_name: "Demo Module 1"
+---
+
+# Basic Task Page
+
+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/templates/addon-resources/resources/interactive-tasks/index.mdx

@@ -0,0 +1,93 @@
+---
+title: Interactive Tasks
+sidebar_custom_props:
+  sidebar_task_hide_progress: true
+sidebar_class_name: sidebar-logo-docusaurus
+---
+
+import { Iconify } from "@sp-days-framework/docusaurus-frontpage-collection";
+
+<div align="center">
+  <div className="resourceLandingPage">
+    <Iconify icon="logos:docusaurus" width="105px"/>
+  </div>
+  <div align="center">
+    # Docusaurus Interactive Tasks
+  </div>
+  <div align="center">
+    <p>
+        *A Docusaurus plugin that transforms documentation into interactive learning experiences!*
+    </p>
+    <h4>
+        [Setup](./setup/index.mdx)
+        ·
+        [NPM Package](https://www.npmjs.com/package/@sp-days-framework/docusaurus-plugin-interactive-tasks)
+        ·
+        [Source Code](https://github.com/helse-sorost/sp-days-framework)
+    </h4>
+  </div>
+</div>
+
+---
+
+## Features
+
+- **Interactive Tasks** - Collapsible task components with completion tracking
+- **Hints & Solutions** - Optional toggleable hints and solutions 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.
+:::
+
+:::solution
+```bash
+npm install @sp-days-framework/docusaurus-plugin-interactive-tasks
+```
+:::
+
+::::
+````
+
+<div className="preview">
+  <div className="container" style={{ width: '-webkit-fill-available' }}>
+    ::::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.
+    :::
+
+    :::solution
+    ```bash
+    npm install @sp-days-framework/docusaurus-plugin-interactive-tasks
+    ```
+    :::
+
+    ::::
+  </div>
+</div>
+<br>
+</br>
+
+Tasks are automatically numbered, track completion in localStorage, and sync across browser tabs. See [Setup](./setup/index.mdx) for installation and configuration.
+
+## Documentation
+
+- **[Creating Tasks](./creating-tasks.mdx)** - Learn the task directive syntax
+- **[Task Progression](./task-progression.mdx)** - Display progress with components
+- **[Advanced Configuration](./setup/advanced-configuration.mdx)** - Detailed options and internals

package/templates/addon-resources/resources/interactive-tasks/setup/advanced-configuration.mdx

@@ -0,0 +1,150 @@
+---
+title: Advanced
+sidebar_position: 2
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Advanced Configuration
+
+## Frontmatter Options Reference
+
+| 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. |