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

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+import type { Token, Tokens } from 'marked';
+/**
+ * Comment types
+ */
+export type CommentType = 'note' | 'question' | 'suggestion' | 'issue' | 'internal' | 'review' | 'todo';
+/**
+ * Comment visibility levels
+ */
+export type CommentVisibility = 'public' | 'private' | 'dev-only' | 'editors-only';
+/**
+ * Comment status
+ */
+export type CommentStatus = 'open' | 'resolved' | 'archived';
+/**
+ * Metadata for a comment
+ */
+export interface CommentMeta {
+    author?: string;
+    date?: string;
+    type?: CommentType;
+    visibility?: CommentVisibility;
+    status?: CommentStatus;
+    priority?: 'low' | 'medium' | 'high';
+    tags?: string;
+    id?: string;
+    replyTo?: string;
+    resolved?: string;
+    className?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Token for inline comments
+ */
+export interface InlineCommentToken extends Tokens.Generic {
+    type: 'inlineComment';
+    raw: string;
+    text: string;
+    meta: CommentMeta;
+    tokens?: Token[];
+}
+/**
+ * Token for block comments
+ */
+export interface BlockCommentToken extends Tokens.Generic {
+    type: 'blockComment';
+    raw: string;
+    text: string;
+    meta: CommentMeta;
+    tokens?: Token[];
+}
+/**
+ * Options for the comment extension
+ */
+export interface CommentOptions {
+    /**
+     * CSS class prefix for comment elements
+     * @default 'marked-extended-comment'
+     */
+    className?: string;
+    /**
+     * Prefix for generating unique IDs
+     * @default 'comment'
+     */
+    prefixId?: string;
+    /**
+     * Show comments by default
+     * @default true
+     */
+    showComments?: boolean;
+    /**
+     * Enable inline comments
+     * @default true
+     */
+    enableInlineComments?: boolean;
+    /**
+     * Enable block comments
+     * @default true
+     */
+    enableBlockComments?: boolean;
+    /**
+     * Show comment metadata (author, date, etc.)
+     * @default true
+     */
+    showMetadata?: boolean;
+    /**
+     * Show resolved comments
+     * @default false
+     */
+    showResolvedComments?: boolean;
+    /**
+     * Default comment type
+     * @default 'note'
+     */
+    defaultType?: CommentType;
+    /**
+     * Default visibility
+     * @default 'public'
+     */
+    defaultVisibility?: CommentVisibility;
+    /**
+     * Filter comments by visibility
+     * @default []
+     */
+    visibilityFilter?: CommentVisibility[];
+    /**
+     * Filter comments by type
+     * @default []
+     */
+    typeFilter?: CommentType[];
+    /**
+     * Custom template for inline comments
+     */
+    inlineTemplate?: string;
+    /**
+     * Custom template for block comments
+     */
+    blockTemplate?: string;
+    /**
+     * Inject CSS styles
+     * @default true
+     */
+    injectStyles?: boolean;
+    /**
+     * Custom callback to modify comment tokens
+     */
+    customizeToken?: (token: InlineCommentToken | BlockCommentToken) => void;
+    /**
+     * Callback when comment visibility changes
+     */
+    onVisibilityChange?: (commentId: string, visible: boolean) => void;
+    /**
+     * Callback when comment is resolved/unresolved
+     */
+    onStatusChange?: (commentId: string, status: CommentStatus) => void;
+}
+/**
+ * Renderer options for comments
+ */
+export interface CommentRendererOptions {
+    commentId: string;
+    meta: CommentMeta;
+    content: string;
+    isInline: boolean;
+    className: string;
+    showMetadata: boolean;
+    template?: string;
+}

package/dist/utils/constants.d.ts

@@ -0,0 +1,29 @@
+import type { CommentOptions } from '../types';
+/**
+ * Default options for the comment extension
+ */
+export declare const DEFAULT_OPTIONS: Required<Omit<CommentOptions, 'customizeToken' | 'onVisibilityChange' | 'onStatusChange' | 'inlineTemplate' | 'blockTemplate' | 'visibilityFilter' | 'typeFilter'>>;
+/**
+ * Comment type SVG icons
+ */
+export declare const COMMENT_ICONS: Record<string, string>;
+/**
+ * Comment type labels
+ */
+export declare const COMMENT_LABELS: Record<string, string>;
+/**
+ * Default template for inline comments
+ */
+export declare const DEFAULT_INLINE_TEMPLATE = "\n<span class=\"{className} {className}-inline {className}-type-{type} {className}-status-{status} {visibilityClass}\" \n      id=\"{commentId}\"\n      data-comment-type=\"{type}\"\n      data-comment-status=\"{status}\"\n      data-comment-visibility=\"{visibility}\"\n      data-comment-author=\"{author}\"\n      data-comment-date=\"{date}\"\n      role=\"note\"\n      aria-label=\"Comment: {text}\"\n      title=\"{tooltipText}\">\n  <span class=\"{className}-content\">{content}</span>\n  <span class=\"{className}-indicator\" aria-hidden=\"true\">{icon}</span>\n</span>\n";
+/**
+ * Default template for block comments
+ */
+export declare const DEFAULT_BLOCK_TEMPLATE = "\n<aside class=\"{className} {className}-block {className}-type-{type} {className}-status-{status} {visibilityClass} {priorityClass}\"\n       id=\"{commentId}\"\n       data-comment-type=\"{type}\"\n       data-comment-status=\"{status}\"\n       data-comment-visibility=\"{visibility}\"\n       data-comment-author=\"{author}\"\n       data-comment-date=\"{date}\"\n       role=\"complementary\"\n       aria-label=\"Comment by {author}\">\n  <div class=\"{className}-header\">\n    <span class=\"{className}-icon\" aria-hidden=\"true\">{icon}</span>\n    <span class=\"{className}-type-label\">{typeLabel}</span>\n    {metadata}\n  </div>\n  <div class=\"{className}-body\">\n    {content}\n  </div>\n</aside>\n";
+/**
+ * Metadata template
+ */
+export declare const METADATA_TEMPLATE = "\n<div class=\"{className}-metadata\">\n  {authorInfo}\n  {dateInfo}\n  {tagsInfo}\n  {priorityInfo}\n</div>\n";
+/**
+ * Default structural styles for comments (minimal, layout-only)
+ */
+export declare const DEFAULT_STYLES = "\n.marked-extended-comment { position: relative; display: inline-block; }\n.marked-extended-comment-inline { display: inline; }\n.marked-extended-comment-indicator { position: absolute; top: -8px; right: -8px; font-size: 12px; line-height: 1; }\n.marked-extended-comment-block { display: block; margin: 1rem 0; }\n.marked-extended-comment-header { display: flex; align-items: center; gap: 0.5rem; margin-bottom: 0.5rem; }\n.marked-extended-comment-icon { line-height: 1; }\n.marked-extended-comment-body { margin: 0.5rem 0; }\n.marked-extended-comment-metadata { display: flex; flex-wrap: wrap; gap: 0.75rem; margin-top: 0.5rem; }\n.marked-extended-comment-metadata > span { display: flex; align-items: center; gap: 0.25rem; }\n.marked-extended-comment.hidden { display: none; }\n";

package/dist/utils/helpers.d.ts

@@ -0,0 +1,30 @@
+export declare function generateUniqueId(prefix?: string): string;
+/**
+ * Reset the comment counter (useful for testing)
+ */
+export declare function resetCommentCounter(): void;
+/**
+ * Parse property string like 'author="John" type="note"'
+ */
+export declare function parsePropString(propString: string): Record<string, string>;
+/**
+ * Replace template placeholders with values
+ */
+export declare function replaceTemplatePlaceholders(template: string, values: Record<string, string>): string;
+/**
+ * Format date string
+ */
+export declare function formatDate(dateString?: string): string;
+/**
+ * Check if comment should be shown based on visibility and filters
+ */
+export declare function shouldShowComment(visibility?: string, status?: string, type?: string, visibilityFilter?: string[], typeFilter?: string[], showResolved?: boolean): boolean;
+/**
+ * Build metadata HTML for comments
+ */
+export declare function buildMetadataHtml(author?: string, date?: string, tags?: string, priority?: string, className?: string): {
+    authorInfo: string;
+    dateInfo: string;
+    tagsInfo: string;
+    priorityInfo: string;
+};

package/dist/utils/inject-styles.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Ensure styles are injected into the document
+ */
+export declare function ensureStyles(id: string, styles: string): void;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@fsegurai/marked-extended-comments",
+  "version": "17.0.0-beta.0",
+  "description": "Marked extension for collaborative comments and annotations",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.esm.js",
+  "browser": "./dist/index.umd.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "keywords": [
+    "extensions",
+    "javascript",
+    "library",
+    "markdown",
+    "markedjs",
+    "marked-extended-comments",
+    "parser",
+    "syntax",
+    "typescript"
+  ],
+  "author": {
+    "name": "Fabián Segura",
+    "url": "https://www.fsegurai.com/"
+  },
+  "license": "MIT",
+  "scripts": {
+    "prepare": "rollup -c rollup.config.js",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage"
+  },
+  "peerDependencies": {
+    "marked": ">=17.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fsegurai/marked-extensions.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fsegurai/marked-extensions/issues"
+  },
+  "homepage": "https://github.com/fsegurai/marked-extensions#readme"
+}

package/src/global.d.ts

@@ -0,0 +1,13 @@
+declare global {
+  interface Window {
+    __injectedStyles__?: Record<string, boolean>;
+  }
+}
+
+declare module 'marked' {
+  interface TokensList {
+    kanban?: import('./types').CommentType;
+  }
+}
+
+export {};

package/src/index.ts

@@ -0,0 +1,103 @@
+import type { Token } from 'marked';
+import { ensureStyles } from './utils/inject-styles';
+import { DEFAULT_OPTIONS, DEFAULT_STYLES } from './utils/constants';
+import {
+  createBlockCommentRenderer,
+  createBlockCommentTokenizer,
+  createInlineCommentRenderer,
+  createInlineCommentTokenizer,
+} from './tokenizer';
+import type { BlockCommentToken, CommentOptions, InlineCommentToken } from './types';
+
+// Export types for external use
+export type {
+  CommentOptions,
+  InlineCommentToken,
+  BlockCommentToken,
+  CommentMeta,
+  CommentType,
+  CommentVisibility,
+  CommentStatus,
+} from './types';
+
+/**
+ * Marked Extended Comments extension
+ * Adds support for inline and block comments with rich metadata
+ *
+ * @example
+ * ```markdown
+ * // Inline comment
+ * This text has :::comment{author="Alice" type="note"}a comment::: here.
+ *
+ * // Block comment
+ * ::::comment{author="Bob" type="review" status="open"}
+ * This section needs revision.
+ * ::::commentend
+ * ```
+ *
+ * @param options - Configuration options
+ * @returns Marked extension object
+ */
+export default function markedExtendedComments(options: CommentOptions = {}) {
+  // Merge options with defaults
+  const config = { ...DEFAULT_OPTIONS, ...options } as Required<CommentOptions>;
+
+  // Inject styles if needed
+  if (config.injectStyles) {
+    ensureStyles('marked-extended-comments-styles', DEFAULT_STYLES);
+  }
+
+  // Return the extension
+  return {
+    walkTokens(token: Token) {
+      // Handle inline comments
+      if (token.type === 'inlineComment') {
+        const commentToken = token as InlineCommentToken;
+
+        // Apply custom token modifications if configured
+        if (config.customizeToken && typeof config.customizeToken === 'function') {
+          config.customizeToken(commentToken);
+        }
+
+        // Trigger visibility change callback
+        if (config.onVisibilityChange && typeof config.onVisibilityChange === 'function') {
+          const commentId = commentToken.meta.id || `${config.prefixId}-${Date.now()}`;
+          const visible = config.showComments
+                         && (commentToken.meta.status !== 'resolved' || config.showResolvedComments);
+          config.onVisibilityChange(commentId, visible);
+        }
+      }
+
+      // Handle block comments
+      if (token.type === 'blockComment') {
+        const commentToken = token as BlockCommentToken;
+
+        // Apply custom token modifications if configured
+        if (config.customizeToken && typeof config.customizeToken === 'function') {
+          config.customizeToken(commentToken);
+        }
+
+        // Trigger visibility change callback
+        if (config.onVisibilityChange && typeof config.onVisibilityChange === 'function') {
+          const commentId = commentToken.meta.id || `${config.prefixId}-${Date.now()}`;
+          const visible = config.showComments
+                         && (commentToken.meta.status !== 'resolved' || config.showResolvedComments);
+          config.onVisibilityChange(commentId, visible);
+        }
+
+        // Trigger status change callback
+        if (config.onStatusChange && typeof config.onStatusChange === 'function' && commentToken.meta.status) {
+          const commentId = commentToken.meta.id || `${config.prefixId}-${Date.now()}`;
+          config.onStatusChange(commentId, commentToken.meta.status);
+        }
+      }
+    },
+    extensions: [
+      createInlineCommentTokenizer(config),
+      createBlockCommentTokenizer(config),
+      createInlineCommentRenderer(config),
+      createBlockCommentRenderer(config),
+    ],
+  };
+}
+

package/src/renderer.ts

@@ -0,0 +1,126 @@
+import type { Token } from 'marked';
+import {
+  COMMENT_ICONS,
+  COMMENT_LABELS,
+  DEFAULT_BLOCK_TEMPLATE,
+  DEFAULT_INLINE_TEMPLATE,
+  METADATA_TEMPLATE,
+} from './utils/constants';
+import { buildMetadataHtml, replaceTemplatePlaceholders } from './utils/helpers';
+import type { CommentMeta } from './types';
+
+/**
+ * Render options for comments
+ */
+interface RenderOptions {
+  commentId: string;
+  meta: CommentMeta;
+  text: string;
+  tokens: Token[];
+  parser: { parse: (tokens: Token[]) => string; parseInline: (tokens: Token[]) => string };
+  className: string;
+  template?: string;
+  showMetadata: boolean;
+}
+
+/**
+ * Render an inline comment
+ */
+export function renderInlineComment(options: RenderOptions): string {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { commentId, meta, text, className, template, showMetadata } = options;
+
+  const type = meta.type || 'note';
+  const status = meta.status || 'open';
+  const visibility = meta.visibility || 'public';
+  const icon = COMMENT_ICONS[type] || '📝';
+
+  // Build visibility class
+  const visibilityClass = visibility !== 'public' ? `${className}-visibility-${visibility}` : '';
+
+  // Build tooltip text
+  const tooltipParts: string[] = [];
+  if (meta.author) tooltipParts.push(`Author: ${meta.author}`);
+  if (meta.type) tooltipParts.push(`Type: ${COMMENT_LABELS[meta.type] || meta.type}`);
+  if (meta.date) tooltipParts.push(`Date: ${meta.date}`);
+  const tooltipText = tooltipParts.join(' | ');
+
+  const templateToUse = template || DEFAULT_INLINE_TEMPLATE;
+
+  return replaceTemplatePlaceholders(templateToUse, {
+    className,
+    commentId,
+    type,
+    status,
+    visibility,
+    visibilityClass,
+    author: meta.author || '',
+    date: meta.date || '',
+    text,
+    content: text,
+    icon,
+    tooltipText,
+  });
+}
+
+/**
+ * Render a block comment
+ */
+export function renderBlockComment(options: RenderOptions): string {
+  const { commentId, meta, tokens, parser, className, template, showMetadata } = options;
+
+  const type = meta.type || 'note';
+  const status = meta.status || 'open';
+  const visibility = meta.visibility || 'public';
+  const priority = meta.priority || '';
+  const icon = COMMENT_ICONS[type] || '📝';
+  const typeLabel = COMMENT_LABELS[type] || type;
+
+  // Build visibility class
+  const visibilityClass = visibility !== 'public' ? `${className}-visibility-${visibility}` : '';
+
+  // Build priority class
+  const priorityClass = priority ? `${className}-priority-${priority}` : '';
+
+  // Parse comment content (nested markdown)
+  const content = parser.parse(tokens);
+
+  // Build metadata HTML
+  let metadata = '';
+  if (showMetadata) {
+    const { authorInfo, dateInfo, tagsInfo, priorityInfo } = buildMetadataHtml(
+      meta.author,
+      meta.date,
+      meta.tags,
+      meta.priority,
+      className,
+    );
+
+    metadata = replaceTemplatePlaceholders(METADATA_TEMPLATE, {
+      className,
+      authorInfo,
+      dateInfo,
+      tagsInfo,
+      priorityInfo,
+    });
+  }
+
+  const templateToUse = template || DEFAULT_BLOCK_TEMPLATE;
+
+  return replaceTemplatePlaceholders(templateToUse, {
+    className,
+    commentId,
+    type,
+    status,
+    visibility,
+    visibilityClass,
+    priorityClass,
+    author: meta.author || '',
+    date: meta.date || '',
+    icon,
+    typeLabel,
+    content,
+    metadata,
+  });
+}
+

package/src/tokenizer.ts

@@ -0,0 +1,161 @@
+import type { RendererExtension, TokenizerExtension } from 'marked';
+import { generateUniqueId, parsePropString } from './utils/helpers';
+import { renderBlockComment, renderInlineComment } from './renderer';
+import type { BlockCommentToken, CommentMeta, CommentOptions, InlineCommentToken } from './types';
+
+/**
+ * Create an inline comment tokenizer
+ */
+export function createInlineCommentTokenizer(options: Required<Omit<CommentOptions, 'customizeToken' | 'onVisibilityChange' | 'onStatusChange' | 'inlineTemplate' | 'blockTemplate' | 'visibilityFilter' | 'typeFilter'>>): TokenizerExtension {
+  return {
+    name: 'inlineComment',
+    level: 'inline',
+    start(src: string) {
+      return src.indexOf(':::comment');
+    },
+    tokenizer(src: string): InlineCommentToken | undefined {
+      // Regex for inline comments: :::comment{props}text:::
+      const match = src.match(/^:::comment(?:\{([^}]*)\})?([^:]+):::/);
+
+      if (!match) return undefined;
+
+      const [raw, propString = '', text] = match;
+
+      // Parse properties
+      const props = parsePropString(propString);
+
+      const meta: CommentMeta = {
+        author: props['author'],
+        date: props['date'],
+        type: (props['type'] as CommentMeta['type']) || options.defaultType,
+        visibility: (props['visibility'] as CommentMeta['visibility']) || options.defaultVisibility,
+        status: (props['status'] as CommentMeta['status']) || 'open',
+        priority: props['priority'] as CommentMeta['priority'],
+        tags: props['tags'],
+        id: props['id'],
+        className: props['className'],
+      };
+
+      return {
+        type: 'inlineComment',
+        raw,
+        text: text.trim(),
+        meta,
+      };
+    },
+  };
+}
+
+/**
+ * Create block comment tokenizer
+ */
+export function createBlockCommentTokenizer(options: Required<Omit<CommentOptions, 'customizeToken' | 'onVisibilityChange' | 'onStatusChange' | 'inlineTemplate' | 'blockTemplate' | 'visibilityFilter' | 'typeFilter'>>): TokenizerExtension {
+  return {
+    name: 'blockComment',
+    level: 'block',
+    tokenizer(src: string): BlockCommentToken | undefined {
+      // Regex for block comments: ::::comment{props}\ncontent\n::::commentend
+      const match = src.match(/^::::comment(?:\{([^}]*)\})?\s*\n([\s\S]*?)::::commentend/);
+
+      if (!match) return undefined;
+
+      const [raw, propString = '', content] = match;
+
+      // Parse properties
+      const props = parsePropString(propString);
+
+      const meta: CommentMeta = {
+        author: props['author'],
+        date: props['date'],
+        type: (props['type'] as CommentMeta['type']) || options.defaultType,
+        visibility: (props['visibility'] as CommentMeta['visibility']) || options.defaultVisibility,
+        status: (props['status'] as CommentMeta['status']) || 'open',
+        priority: props['priority'] as CommentMeta['priority'],
+        tags: props['tags'],
+        id: props['id'],
+        replyTo: props['replyTo'],
+        className: props['className'],
+      };
+
+      // Tokenize the content
+      const tokens = this.lexer.blockTokens(content.trim());
+
+      return {
+        type: 'blockComment',
+        raw,
+        text: content.trim(),
+        meta,
+        tokens,
+      };
+    },
+  };
+}
+
+/**
+ * Create renderer for inline comments
+ */
+export function createInlineCommentRenderer(
+  options: Required<Omit<CommentOptions, 'customizeToken' | 'onVisibilityChange' | 'onStatusChange' | 'visibilityFilter' | 'typeFilter'>>,
+): RendererExtension {
+  return {
+    name: 'inlineComment',
+    renderer(token): string {
+      const commentToken = token as InlineCommentToken;
+      const meta = commentToken.meta;
+
+      // Check if comment should be shown
+      if (!options.showComments) return commentToken.text;
+      if (!options.enableInlineComments) return commentToken.text;
+      if (meta.status === 'resolved' && !options.showResolvedComments) return commentToken.text;
+
+      // Generate unique ID
+      const commentId = meta.id || generateUniqueId(options.prefixId);
+
+      return renderInlineComment({
+        commentId,
+        meta,
+        text: commentToken.text,
+        tokens: [],
+        parser: this.parser,
+        className: meta.className || options.className,
+        template: options.inlineTemplate,
+        showMetadata: options.showMetadata,
+      });
+    },
+  };
+}
+
+/**
+ * Create renderer for block comments
+ */
+export function createBlockCommentRenderer(
+  options: Required<Omit<CommentOptions, 'customizeToken' | 'onVisibilityChange' | 'onStatusChange' | 'visibilityFilter' | 'typeFilter'>>,
+): RendererExtension {
+  return {
+    name: 'blockComment',
+    renderer(token): string {
+      const commentToken = token as BlockCommentToken;
+      const meta = commentToken.meta;
+
+      // Check if comment should be shown
+      if (!options.showComments) return '';
+      if (!options.enableBlockComments) return '';
+      if (meta.status === 'resolved' && !options.showResolvedComments) return '';
+
+      // Generate unique ID
+      const commentId = meta.id || generateUniqueId(options.prefixId);
+
+      return renderBlockComment({
+        commentId,
+        meta,
+        text: commentToken.text,
+        tokens: commentToken.tokens || [],
+        parser: this.parser,
+        className: meta.className || options.className,
+        template: options.blockTemplate,
+        showMetadata: options.showMetadata,
+      });
+    },
+  };
+}
+