@fsegurai/marked-extended-comments 17.0.0-beta.0

package/README.md

@@ -0,0 +1,682 @@
+<p align="center">
+  <img alt="Marked Extensions Logo" src="https://raw.githubusercontent.com/fsegurai/marked-extensions/main/public/marked-extensions.svg">
+</p>
+
+<p align="center">
+  <a href="https://github.com/fsegurai/marked-extensions">
+      <img src="https://img.shields.io/azure-devops/build/fsegurai/93779823-473d-4fb3-a5b1-27aaa1a88ea2/18/main?label=Build%20Status&"
+          alt="Build Main Status">
+  </a>
+  <a href="https://www.npmjs.org/package/@fsegurai/marked-extended-comments">
+      <img src="https://img.shields.io/npm/v/@fsegurai/marked-extended-comments.svg"
+          alt="Latest Release">
+  </a>
+  <br>
+  <img alt="GitHub contributors" src="https://img.shields.io/github/contributors/fsegurai/marked-extensions">
+  <img alt="Dependency status for repo" src="https://img.shields.io/librariesio/github/fsegurai/marked-extensions">
+  <a href="https://opensource.org/licenses/MIT">
+    <img alt="GitHub License" src="https://img.shields.io/github/license/fsegurai/marked-extensions">
+  </a>
+  <br>
+  <img alt="Stars" src="https://img.shields.io/github/stars/fsegurai/marked-extensions?style=square&labelColor=343b41"/> 
+  <img alt="Forks" src="https://img.shields.io/github/forks/fsegurai/marked-extensions?style=square&labelColor=343b41"/>
+</p>
+
+**An extension library for Marked.js to enhance Markdown rendering.**
+
+`@fsegurai/marked-extended-comments` Marked extension for collaborative comments and annotations
+
+---
+
+This extension enables powerful commenting capabilities directly in Markdown, allowing teams to annotate documents,
+track feedback, manage review processes, and collaborate on content creation. Comments can be styled by type, filtered
+by status, and customized to fit your workflow.
+
+### Table of contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+	- [Basic Usage](#basic-usage)
+- [Inline Comments](#inline-comments)
+	- [Block Comments](#block-comments)
+
+- [Comment Types](#comment-types)
+    - [Configuration Options](#configuration-options)
+    - [Properties](#properties)
+    - [Advanced Examples](#advanced-examples)
+- [More Resources](#more-resources)
+	- [Available Extensions](#available-extensions)
+	- [Demo Application](#demo-application)
+- [License](#license)
+
+## Installation
+
+To add `@fsegurai/marked-extended-comments` along with Marked.js to your `package.json` use the following commands.
+
+```bash
+bun install @fsegurai/marked-extended-comments marked@>=17.0.0 --save
+```
+
+## Usage
+
+### Basic Usage
+
+Import `@fsegurai/marked-extended-comments` and apply it to your Marked instance as shown below.
+
+**Comments use two syntaxes: `:::comment` for inline and `::::comment` for block comments.**
+
+```javascript
+import { marked } from 'marked';
+import markedExtendedComments from '@fsegurai/marked-extended-comments';
+
+// or UMD script
+// <script src="https://cdn.jsdelivr.net/npm/marked/lib/marked.umd.js"></script>
+// <script src="https://cdn.jsdelivr.net/npm/@fsegurai/marked-extended-comments/lib/index.umd.js"></script>
+
+marked.use(markedExtendedComments());
+
+const markdown = `
+This text has :::comment{author="Alice"}a note::: embedded inline.
+
+::::comment{author="Bob" type="review" status="open"}
+This section needs revision.
+
+**Action items:**
+
+- Verify statistics
+- Add citations
+  ::::commentend
+  `;
+
+marked.parse(markdown);
+```
+
+The extension supports **nested Markdown content** within block comments, including lists, code blocks, links, and all
+other Markdown formatting. Comments are rendered with semantic HTML and include proper accessibility attributes.
+
+### Styling Your Comments
+
+This extension follows a **separation of concerns** approach, injecting only minimal structural CSS. Visual styling is
+completely separated for maximum flexibility.
+
+#### Generated HTML Structure
+
+**Inline Comments:**
+
+```html
+<span class="marked-extended-comment marked-extended-comment-inline marked-extended-comment-type-note">
+  <span class="marked-extended-comment-indicator" title="Comment by Alice">💬</span>
+  <span class="marked-extended-comment-text">inline text</span>
+</span>
+```
+
+**Block Comments:**
+
+```html
+
+<div class="marked-extended-comment marked-extended-comment-block marked-extended-comment-type-review">
+    <div class="marked-extended-comment-header">
+        <span class="marked-extended-comment-icon">💬</span>
+        <span class="marked-extended-comment-type-label">Review</span>
+        <span class="marked-extended-comment-metadata">
+      <span class="marked-extended-comment-author">By Alice</span>
+      <span class="marked-extended-comment-status">Open</span>
+    </span>
+    </div>
+    <div class="marked-extended-comment-body">
+        <!-- Markdown content rendered here -->
+    </div>
+</div>
+```
+
+#### CSS Classes Reference
+
+| Class                                      | Purpose                 | Type   |
+|--------------------------------------------|-------------------------|--------|
+| `.marked-extended-comment`                 | Base comment wrapper    | Both   |
+| `.marked-extended-comment-inline`          | Inline comment style    | Inline |
+| `.marked-extended-comment-block`           | Block comment style     | Block  |
+| `.marked-extended-comment-type-note`       | Note type styling       | Both   |
+| `.marked-extended-comment-type-review`     | Review type styling     | Both   |
+| `.marked-extended-comment-type-question`   | Question type styling   | Both   |
+| `.marked-extended-comment-type-suggestion` | Suggestion type styling | Both   |
+| `.marked-extended-comment-indicator`       | Inline comment icon     | Inline |
+| `.marked-extended-comment-text`            | Inline comment text     | Inline |
+| `.marked-extended-comment-header`          | Block comment header    | Block  |
+| `.marked-extended-comment-icon`            | Block comment icon      | Block  |
+| `.marked-extended-comment-type-label`      | Type label text         | Block  |
+| `.marked-extended-comment-metadata`        | Author/status info      | Block  |
+| `.marked-extended-comment-body`            | Block comment content   | Block  |
+
+#### Complete Styling Example
+
+```css
+/* Base comment styles */
+.marked-extended-comment {
+    transition: all 0.2s ease;
+}
+
+/* Inline Comments */
+.marked-extended-comment-inline {
+    background: rgba(255, 235, 59, 0.2);
+    border-bottom: 2px dashed rgba(255, 235, 59, 0.8);
+    padding: 0 4px;
+    cursor: help;
+    border-radius: 2px;
+    position: relative;
+}
+
+.marked-extended-comment-inline:hover {
+    background: rgba(255, 235, 59, 0.3);
+    border-bottom-color: rgba(255, 235, 59, 1);
+}
+
+.marked-extended-comment-indicator {
+    font-size: 0.875em;
+    opacity: 0.8;
+    margin-right: 2px;
+}
+
+/* Block Comments */
+.marked-extended-comment-block {
+    padding: 1rem;
+    margin: 1rem 0;
+    border-left: 4px solid;
+    border-radius: 4px;
+    background: rgba(0, 0, 0, 0.03);
+}
+
+.marked-extended-comment-header {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin-bottom: 0.75rem;
+    padding-bottom: 0.5rem;
+    border-bottom: 1px solid rgba(0, 0, 0, 0.1);
+}
+
+.marked-extended-comment-icon {
+    font-size: 1.2em;
+}
+
+.marked-extended-comment-type-label {
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    font-size: 0.875rem;
+}
+
+.marked-extended-comment-metadata {
+    margin-left: auto;
+    display: flex;
+    gap: 0.75rem;
+    font-size: 0.75rem;
+    color: rgba(0, 0, 0, 0.6);
+}
+
+.marked-extended-comment-body {
+    line-height: 1.6;
+}
+
+/* Comment Types - Note */
+.marked-extended-comment-type-note {
+    border-color: #2196F3;
+}
+
+.marked-extended-comment-type-note.marked-extended-comment-inline {
+    background: rgba(33, 150, 243, 0.15);
+    border-bottom-color: rgba(33, 150, 243, 0.6);
+}
+
+.marked-extended-comment-type-note.marked-extended-comment-block {
+    background: rgba(33, 150, 243, 0.05);
+}
+
+.marked-extended-comment-type-note .marked-extended-comment-type-label {
+    color: #2196F3;
+}
+
+/* Comment Types - Review */
+.marked-extended-comment-type-review {
+    border-color: #9C27B0;
+}
+
+.marked-extended-comment-type-review.marked-extended-comment-inline {
+    background: rgba(156, 39, 176, 0.15);
+    border-bottom-color: rgba(156, 39, 176, 0.6);
+}
+
+.marked-extended-comment-type-review.marked-extended-comment-block {
+    background: rgba(156, 39, 176, 0.05);
+}
+
+.marked-extended-comment-type-review .marked-extended-comment-type-label {
+    color: #9C27B0;
+}
+
+/* Comment Types - Question */
+.marked-extended-comment-type-question {
+    border-color: #FF9800;
+}
+
+.marked-extended-comment-type-question.marked-extended-comment-inline {
+    background: rgba(255, 152, 0, 0.15);
+    border-bottom-color: rgba(255, 152, 0, 0.6);
+}
+
+.marked-extended-comment-type-question.marked-extended-comment-block {
+    background: rgba(255, 152, 0, 0.05);
+}
+
+.marked-extended-comment-type-question .marked-extended-comment-type-label {
+    color: #FF9800;
+}
+
+/* Comment Types - Suggestion */
+.marked-extended-comment-type-suggestion {
+    border-color: #4CAF50;
+}
+
+.marked-extended-comment-type-suggestion.marked-extended-comment-inline {
+    background: rgba(76, 175, 80, 0.15);
+    border-bottom-color: rgba(76, 175, 80, 0.6);
+}
+
+.marked-extended-comment-type-suggestion.marked-extended-comment-block {
+    background: rgba(76, 175, 80, 0.05);
+}
+
+.marked-extended-comment-type-suggestion .marked-extended-comment-type-label {
+    color: #4CAF50;
+}
+```
+
+#### Dark Mode Support
+
+```css
+/* Light theme */
+body.light .marked-extended-comment-block {
+    background: rgba(0, 0, 0, 0.03);
+}
+
+body.light .marked-extended-comment-metadata {
+    color: rgba(0, 0, 0, 0.6);
+}
+
+body.light .marked-extended-comment-body {
+    color: #24292e;
+}
+
+/* Dark theme */
+body.dark .marked-extended-comment-block {
+    background: rgba(255, 255, 255, 0.05);
+}
+
+body.dark .marked-extended-comment-metadata {
+    color: rgba(255, 255, 255, 0.6);
+}
+
+body.dark .marked-extended-comment-body {
+    color: #d1d5da;
+}
+
+body.dark .marked-extended-comment-header {
+    border-bottom-color: rgba(255, 255, 255, 0.1);
+}
+```
+
+#### SVG Icon Styling
+
+The extension uses SVG icons for each comment type. You can customize their appearance:
+
+```css
+/* Base SVG icon styling */
+.comment-icon {
+    display: inline-block;
+    vertical-align: middle;
+    width: 16px;
+    height: 16px;
+}
+
+/* Larger icons in block comment headers */
+.marked-extended-comment-icon .comment-icon {
+    width: 20px;
+    height: 20px;
+}
+
+/* Smaller icons for inline comments */
+.marked-extended-comment-indicator .comment-icon {
+    width: 14px;
+    height: 14px;
+}
+
+/* Color icons by comment type */
+.marked-extended-comment-type-note .comment-icon {
+    color: #2196F3;
+}
+
+.marked-extended-comment-type-question .comment-icon {
+    color: #9C27B0;
+}
+
+.marked-extended-comment-type-suggestion .comment-icon {
+    color: #4CAF50;
+}
+
+.marked-extended-comment-type-issue .comment-icon {
+    color: #F44336;
+}
+
+.marked-extended-comment-type-internal .comment-icon {
+    color: #607D8B;
+}
+
+.marked-extended-comment-type-review .comment-icon {
+    color: #FF9800;
+}
+
+.marked-extended-comment-type-todo .comment-icon {
+    color: #00BCD4;
+}
+```
+
+#### Status-Based Styling
+
+```css
+/* Status indicators */
+.marked-extended-comment-status {
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-weight: 600;
+}
+
+.marked-extended-comment[data-status="open"] .marked-extended-comment-status {
+    background: #22863a;
+    color: white;
+}
+
+.marked-extended-comment[data-status="resolved"] .marked-extended-comment-status {
+    background: #6f42c1;
+    color: white;
+}
+
+.marked-extended-comment[data-status="pending"] .marked-extended-comment-status {
+    background: #f66a0a;
+    color: white;
+}
+```
+
+#### Tooltip for Inline Comments
+
+```css
+/* Add tooltip on hover */
+.marked-extended-comment-inline::after {
+    content: attr(title);
+    position: absolute;
+    bottom: 100%;
+    left: 50%;
+    transform: translateX(-50%);
+    background: #333;
+    color: white;
+    padding: 4px 8px;
+    border-radius: 4px;
+    font-size: 0.75rem;
+    white-space: nowrap;
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 0.2s;
+    margin-bottom: 4px;
+}
+
+.marked-extended-comment-inline:hover::after {
+    opacity: 1;
+}
+```
+
+#### Copy Demo Theme
+
+For complete
+styling: [comment-theme.css](https://github.com/fsegurai/marked-extensions/blob/main/demo/styles/extensions/comment-theme.css)
+
+Check the [demo](https://fsegurai.github.io/marked-extensions) to see all comment types and styles in action.
+
+### Inline Comments
+
+Inline comments appear directly within text, perfect for quick annotations:
+
+```markdown
+This text has :::comment{author="Alice" type="note"}needs verification::: here.
+
+A question: :::comment{type="question"}should we use v2 API?:::
+
+Mark as :::comment{type="issue"}outdated data::: for review.
+```
+
+### Block Comments
+
+Block comments are standalone sections with full Markdown support:
+
+```markdown
+::::comment{author="Editor" type="review" priority="high"}
+This introduction needs strengthening.
+
+**Suggestions:**
+
+- Add a hook to grab reader attention
+- Include recent statistics
+- Mention the main thesis upfront
+  ::::commentend
+
+::::comment{type="internal" visibility="dev-only"}
+**Developer Note:**
+
+TODO: Update after API v2 release.
+Use `/api/v2/data` endpoint.
+::::commentend
+```
+
+## Comment Types
+
+The extension supports 7 comment types with automatic SVG icons and color coding:
+
+| Type         | Icon | Description             | Color  | Use Case                     |
+|--------------|------|-------------------------|--------|------------------------------|
+| `note`       | 📄   | General annotations     | Blue   | Documentation, clarification |
+| `question`   | ❔    | Questions and queries   | Purple | Requesting information       |
+| `suggestion` | 💡   | Improvement suggestions | Green  | Recommendations, ideas       |
+| `issue`      | ⚠️   | Problems and bugs       | Red    | Critical items, errors       |
+| `internal`   | 🔒   | Internal notes          | Grey   | Private team notes           |
+| `review`     | 👁️  | Review comments         | Orange | Editorial feedback           |
+| `todo`       | ✓    | Action items            | Cyan   | Task tracking                |
+
+Each type is automatically styled with appropriate colors and SVG icons. You can set a default type in configuration.
+
+### Configuration Options
+
+The marked-extended-comments extension accepts the following configuration options:
+
+- `className`: The base CSS class name for comments. Defaults to 'marked-extended-comment.'
+- `prefixId`: The prefix ID for comment elements. Defaults to 'comment'.
+- `showComments`: Whether to display comments. Defaults to true.
+- `enableInlineComments`: Enable inline comment syntax. Defaults to true.
+- `enableBlockComments`: Enable block comment syntax. Defaults to true.
+- `showMetadata`: Display comment metadata (author, date, tags). Defaults to true.
+- `showResolvedComments`: Show comments marked as resolved. Defaults to false.
+- `defaultType`: Default comment type when not specified. Defaults to 'note'.
+- `defaultVisibility`: Default visibility level. Defaults to 'public'.
+- `injectStyles`: Whether to inject default styles. Defaults to true.
+- `customizeToken`: Function to customize comment tokens. Defaults to null.
+- `onVisibilityChange`: Callback when comment visibility changes. Defaults to null.
+- `onStatusChange`: Callback when comment status changes. Defaults to null.
+- `inlineTemplate`: Custom HTML template for inline comments. Defaults to built-in template.
+- `blockTemplate`: Custom HTML template for block comments. Defaults to built-in template.
+
+### Properties
+
+Comment syntax supports the following properties:
+
+**Common Properties:**
+
+- `author`: Comment author name
+- `date`: ISO date string (e.g., "2026-02-07")
+- `type`: Comment type ('note', 'question', 'suggestion', 'issue', 'internal', 'review', 'todo')
+- `status`: Comment status ('open', 'resolved', 'archived'). Defaults to 'open'.
+- `visibility`: Visibility level ('public', 'private', 'dev-only', 'editors-only'). Defaults to 'public'.
+- `priority`: Priority level ('low', 'medium', 'high')
+- `tags`: Comma-separated tags
+- `id`: Custom identifier for the comment
+
+**Block Comment Properties:**
+
+- `replyTo`: ID of parent comment for threading
+
+**Example with properties:**
+
+```markdown
+::::comment{
+author="Alice Smith"
+date="2026-02-07"
+type="review"
+status="open"
+priority="high"
+tags="urgent,milestone"
+id="comment-123"
+}
+Review this section carefully before release.
+::::commentend
+```
+
+### Advanced Examples
+
+#### Editorial Workflow
+
+```markdown
+::::comment{author="Chief Editor" type="review" priority="high"}
+This introduction lacks impact. Consider:
+
+1. Start with a compelling statistic
+2. Include a real-world example
+3. State the main argument upfront
+
+**Deadline:** End of week
+::::commentend
+```
+
+#### Code Review Process
+
+```markdown
+::::comment{author="Senior Dev" type="issue" status="open"}
+This function has a potential memory leak in the event handler.
+
+:::comment{type="suggestion"}Consider using WeakMap for automatic cleanup:::
+
+**Priority:** Must fix before merge
+::::commentend
+```
+
+#### Documentation Feedback
+
+```markdown
+The API endpoint :::comment{type="question"}returns JSON or XML?::: can be called with optional parameters.
+
+::::comment{type="note" author="API Team"}
+**Note:** This endpoint will be deprecated in v3.0.
+
+Migration guide: [link to docs]
+::::commentend
+```
+
+#### Task Management
+
+```markdown
+::::comment{type="todo" author="Project Manager" tags="sprint-5,docs"}
+**Sprint Tasks:**
+
+- [ ] Complete API documentation
+- [ ] Add code examples
+- [ ] Review with team
+- [ ] Update changelog
+
+*Due:* End of sprint
+::::commentend
+```
+
+#### Internal Notes
+
+```markdown
+::::comment{type="internal" visibility="dev-only"}
+**Implementation Details:**
+
+This is a temporary workaround until the upstream library fixes the bug.
+Expected fix in v2.1.0 (Q2 2026).
+
+See issue #1234 for tracking.
+::::commentend
+```
+
+#### Status Tracking
+
+```markdown
+::::comment{author="Alice" type="issue" status="resolved"}
+~~The calculation was incorrect.~~
+
+**Resolution:** Fixed in commit abc123
+Formula updated to use correct constant.
+::::commentend
+
+::::comment{type="note" status="archived"}
+Old implementation notes - kept for historical reference.
+::::commentend
+```
+
+#### Visibility Control
+
+```markdown
+::::comment{visibility="private"}
+Private note only visible to authorized users.
+::::commentend
+
+::::comment{visibility="editors-only"}
+Editorial team: Please review for tone and style.
+::::commentend
+
+::::comment{visibility="dev-only"}
+Technical debt: Refactor this section when time permits.
+::::commentend
+```
+
+### Available Extensions
+
+| Extension   | Package                                                                                                      | Version                                                                    | Description                                                          |
+|-------------|--------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|----------------------------------------------------------------------|
+| Accordion   | [@fsegurai/marked-extended-accordion](https://www.npmjs.com/package/@fsegurai/marked-extended-accordion)     | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-accordion)   | Add collapsible accordion sections to your markdown                  |
+| Alert       | [@fsegurai/marked-extended-alert](https://www.npmjs.com/package/@fsegurai/marked-extended-alert)             | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-alert)       | Create styled alert boxes for important information                  |
+| Comments    | [@fsegurai/marked-extended-comments](https://www.npmjs.com/package/@fsegurai/marked-extended-comments)       | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-comments)    | Add comment sections with author and timestamp metadata              |
+| Embeds      | [@fsegurai/marked-extended-embeds](https://www.npmjs.com/package/@fsegurai/marked-extended-embeds)           | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-embeds)      | Easily embed content from various platforms (YouTube, Twitter, etc.) |
+| Footnote    | [@fsegurai/marked-extended-footnote](https://www.npmjs.com/package/@fsegurai/marked-extended-footnote)       | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-footnote)    | Add footnotes with automatic numbering                               |
+| Kanban      | [@fsegurai/marked-extended-kanban](https://www.npmjs.com/package/@fsegurai/marked-extended-kanban)           | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-kanban)      | Create kanban boards with customizable columns and cards             |
+| Lists       | [@fsegurai/marked-extended-lists](https://www.npmjs.com/package/@fsegurai/marked-extended-lists)             | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-lists)       | Enhanced list formatting options                                     |
+| Slide       | [@fsegurai/marked-extended-slide](https://www.npmjs.com/package/@fsegurai/marked-extended-slide)             | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-slide)       | Create slide decks directly from markdown content                    |
+| Spoiler     | [@fsegurai/marked-extended-spoiler](https://www.npmjs.com/package/@fsegurai/marked-extended-spoiler)         | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-spoiler)     | Hide content behind spoiler tags                                     |
+| Tables      | [@fsegurai/marked-extended-tables](https://www.npmjs.com/package/@fsegurai/marked-extended-tables)           | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-tables)      | Advanced table formatting with cell spanning                         |
+| Tabs        | [@fsegurai/marked-extended-tabs](https://www.npmjs.com/package/@fsegurai/marked-extended-tabs)               | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-tabs)        | Create tabbed content sections                                       |
+| Timeline    | [@fsegurai/marked-extended-timeline](https://www.npmjs.com/package/@fsegurai/marked-extended-timeline)       | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-timeline)    | Display content in an interactive timeline format                    |
+| Typographic | [@fsegurai/marked-extended-typographic](https://www.npmjs.com/package/@fsegurai/marked-extended-typographic) | ![npm](https://img.shields.io/npm/v/@fsegurai/marked-extended-typographic) | Improve typography with smart quotes, dashes, and more               |
+
+### Demo Application
+
+To see all extensions in action, check out the [[DEMO]](https://fsegurai.github.io/marked-extensions).
+
+To set up the demo locally, follow the next steps:
+
+```shell
+git clone https://github.com/fsegurai/marked-extensions.git
+bun install
+bun start
+```
+
+This will serve the application locally at [http://[::1]:8000](http://[::1]:8000).
+
+## License
+
+Licensed under [MIT](https://opensource.org/licenses/MIT).