@memberjunction/ng-markdown 0.0.1 → 2.126.0

package/README.md

@@ -1,45 +1,213 @@
 # @memberjunction/ng-markdown
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/ng-markdown`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+A lightweight Angular module for rendering markdown content with rich features including syntax highlighting, Mermaid diagrams, collapsible sections, and more.
+
+## Installation
+
+```bash
+npm install @memberjunction/ng-markdown
+```
+
+## Usage
+
+### Basic Setup
+
+Import the `MarkdownModule` in your Angular module:
+
+```typescript
+import { NgModule } from '@angular/core';
+import { MarkdownModule } from '@memberjunction/ng-markdown';
+
+@NgModule({
+  imports: [
+    MarkdownModule
+  ]
+})
+export class YourModule { }
+```
+
+> **Note**: This module does NOT use `forRoot()`. Simply import `MarkdownModule` in any module where you need markdown rendering. The `MarkdownService` is provided at root level for efficient sharing across the application.
+
+### Basic Usage
+
+```html
+<mj-markdown [data]="markdownContent"></mj-markdown>
+```
+
+### Advanced Usage
+
+```html
+<mj-markdown
+  [data]="content"
+  [enableMermaid]="true"
+  [enableCollapsibleHeadings]="true"
+  [collapsibleHeadingLevel]="2"
+  [autoExpandLevels]="[2]"
+  [enableCodeCopy]="true"
+  [enableAlerts]="true"
+  [enableSmartypants]="true"
+  [enableSvgRenderer]="true"
+  [enableHtml]="false"
+  (rendered)="onRendered($event)"
+  (headingClick)="onHeadingClick($event)"
+  (codeCopied)="onCodeCopied($event)">
+</mj-markdown>
+```
+
+## Features
+
+### Syntax Highlighting (Prism.js)
+Code blocks are automatically highlighted using Prism.js with the Okaidia theme.
+
+### Mermaid Diagrams
+Support for Mermaid diagram rendering:
+
+~~~markdown
+```mermaid
+graph TD
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+~~~
+
+### Collapsible Headings
+Enable collapsible sections with expand/collapse all buttons:
+
+```html
+<mj-markdown
+  [data]="content"
+  [enableCollapsibleHeadings]="true"
+  [collapsibleHeadingLevel]="2"
+  [autoExpandLevels]="[2]">
+</mj-markdown>
+```
+
+- `collapsibleHeadingLevel`: Heading level to start collapsing (1-6)
+- `autoExpandLevels`: Array of heading levels to expand by default (e.g., `[2]` expands only h2)
+- `collapsibleDefaultExpanded`: Whether sections are expanded by default (true/false)
+
+### Copy-to-Clipboard
+Code blocks include a copy button that appears on hover.
+
+### GitHub-Style Alerts
+Support for GitHub-style blockquote alerts:
+
+```markdown
+> [!NOTE]
+> Useful information that users should know.
+
+> [!TIP]
+> Helpful advice for doing things better.
+
+> [!WARNING]
+> Urgent info that needs immediate attention.
+```
+
+### Smartypants Typography
+Automatically converts:
+- "quotes" to "curly quotes"
+- `--` to en-dash (–)
+- `---` to em-dash (—)
+- `...` to ellipsis (…)
+
+### SVG Code Block Rendering
+Render SVG code blocks as actual images:
+
+~~~markdown
+```svg
+<svg width="100" height="100" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="50" cy="50" r="40" fill="blue"/>
+</svg>
+```
+~~~
+
+### HTML Passthrough
+Enable raw HTML rendering for mockups and custom layouts:
+
+```html
+<mj-markdown
+  [data]="content"
+  [enableHtml]="true"
+  [enableJavaScript]="false">
+</mj-markdown>
+```
+
+> **Security Note**: When `enableHtml` is true, JavaScript is still stripped unless `enableJavaScript` is also true. Only enable `enableJavaScript` for fully trusted content.
+
+## Configuration Options
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `data` | `string` | `''` | Markdown content to render |
+| `enableHighlight` | `boolean` | `true` | Enable Prism.js syntax highlighting |
+| `enableMermaid` | `boolean` | `true` | Enable Mermaid diagram rendering |
+| `enableCodeCopy` | `boolean` | `true` | Enable copy button on code blocks |
+| `enableCollapsibleHeadings` | `boolean` | `false` | Enable collapsible heading sections |
+| `collapsibleHeadingLevel` | `1-6` | `2` | Heading level to start collapsing |
+| `collapsibleDefaultExpanded` | `boolean` | `true` | Default expansion state |
+| `autoExpandLevels` | `number[]` | `undefined` | Specific levels to auto-expand |
+| `enableAlerts` | `boolean` | `true` | Enable GitHub-style alerts |
+| `enableSmartypants` | `boolean` | `true` | Enable typography improvements |
+| `enableSvgRenderer` | `boolean` | `true` | Enable SVG code block rendering |
+| `enableHtml` | `boolean` | `false` | Enable raw HTML passthrough |
+| `enableJavaScript` | `boolean` | `false` | Allow JavaScript in HTML (security risk) |
+| `enableHeadingIds` | `boolean` | `true` | Generate heading IDs for anchors |
+| `headingIdPrefix` | `string` | `''` | Prefix for heading IDs |
+| `enableLineNumbers` | `boolean` | `false` | Show line numbers in code blocks |
+| `containerClass` | `string` | `''` | Custom CSS class for container |
+| `mermaidTheme` | `string` | `'default'` | Mermaid theme (default/dark/forest/neutral/base) |
+| `sanitize` | `boolean` | `true` | Sanitize HTML output |
+
+## Events
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `rendered` | `MarkdownRenderEvent` | Emitted when rendering is complete |
+| `headingClick` | `HeadingInfo` | Emitted when a heading is clicked |
+| `codeCopied` | `string` | Emitted when code is copied to clipboard |
+
+## Migration from ngx-markdown
+
+If you're migrating from `ngx-markdown`:
+
+1. Replace imports:
+   ```typescript
+   // Before
+   import { MarkdownModule } from 'ngx-markdown';
+
+   // After
+   import { MarkdownModule } from '@memberjunction/ng-markdown';
+   ```
+
+2. Update module imports (no `forRoot()` needed):
+   ```typescript
+   // Before
+   MarkdownModule.forRoot()
+
+   // After
+   MarkdownModule
+   ```
+
+3. Update template selectors:
+   ```html
+   <!-- Before -->
+   <markdown [data]="content"></markdown>
+
+   <!-- After -->
+   <mj-markdown [data]="content"></mj-markdown>
+   ```
+
+4. The `MarkdownComponent` still exposes an `element` property for backward compatibility with code that accessed `element.nativeElement`.
+
+## Dependencies
+
+- `marked` - Markdown parser
+- `marked-alert` - GitHub-style alerts
+- `marked-highlight` - Syntax highlighting integration
+- `marked-smartypants` - Typography improvements
+- `prismjs` - Syntax highlighting
+- `mermaid` - Diagram rendering
+
+## License
+
+ISC

package/dist/lib/components/markdown.component.d.ts

@@ -0,0 +1,210 @@
+import { EventEmitter, ElementRef, OnChanges, OnDestroy, SimpleChanges, ChangeDetectorRef, AfterViewInit } from '@angular/core';
+import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
+import { MarkdownService } from '../services/markdown.service';
+import { MarkdownRenderEvent, HeadingInfo } from '../types/markdown.types';
+import * as i0 from "@angular/core";
+/**
+ * Angular component for rendering markdown content.
+ *
+ * Features:
+ * - Prism.js syntax highlighting for code blocks
+ * - Mermaid diagram rendering
+ * - Copy-to-clipboard for code blocks
+ * - Collapsible heading sections
+ * - GitHub-style alerts and heading IDs
+ *
+ * Usage:
+ * ```html
+ * <mj-markdown [data]="markdownContent"></mj-markdown>
+ *
+ * <mj-markdown
+ *   [data]="content"
+ *   [enableMermaid]="true"
+ *   [enableCollapsibleHeadings]="true"
+ *   (rendered)="onRendered($event)">
+ * </mj-markdown>
+ * ```
+ */
+export declare class MarkdownComponent implements OnChanges, AfterViewInit, OnDestroy {
+    private elementRef;
+    private sanitizer;
+    private markdownService;
+    private cdr;
+    /**
+     * The markdown content to render
+     */
+    data: string;
+    /**
+     * Enable syntax highlighting
+     */
+    enableHighlight: boolean;
+    /**
+     * Enable Mermaid diagram rendering
+     */
+    enableMermaid: boolean;
+    /**
+     * Enable copy button on code blocks
+     */
+    enableCodeCopy: boolean;
+    /**
+     * Enable collapsible heading sections
+     */
+    enableCollapsibleHeadings: boolean;
+    /**
+     * Heading level at which to start collapsing
+     */
+    collapsibleHeadingLevel: 1 | 2 | 3 | 4 | 5 | 6;
+    /**
+     * Whether collapsible sections should be expanded by default
+     */
+    collapsibleDefaultExpanded: boolean;
+    /**
+     * Specify which heading levels should start expanded.
+     * Array of heading levels (2-6) that should be expanded by default.
+     * Takes precedence over collapsibleDefaultExpanded for specified levels.
+     *
+     * Examples:
+     * - [2] = Only h2 expanded, h3-h6 collapsed
+     * - [2, 3] = h2 and h3 expanded, h4-h6 collapsed
+     * - [] = All collapsed
+     * - undefined = Uses collapsibleDefaultExpanded for all levels
+     */
+    autoExpandLevels?: number[];
+    /**
+     * Enable GitHub-style alerts
+     */
+    enableAlerts: boolean;
+    /**
+     * Enable smartypants for typography (curly quotes, em/en dashes, ellipses)
+     */
+    enableSmartypants: boolean;
+    /**
+     * Enable SVG code block rendering
+     * When enabled, ```svg code blocks are rendered as actual SVG images
+     */
+    enableSvgRenderer: boolean;
+    /**
+     * Enable raw HTML passthrough in markdown content.
+     * Scripts and event handlers are still stripped unless enableJavaScript is true.
+     */
+    enableHtml: boolean;
+    /**
+     * Enable JavaScript in HTML content (<script> tags and on* handlers).
+     * WARNING: Major security risk - only enable for fully trusted content.
+     */
+    enableJavaScript: boolean;
+    /**
+     * Enable heading IDs for anchor links
+     */
+    enableHeadingIds: boolean;
+    /**
+     * Prefix for heading IDs
+     */
+    headingIdPrefix: string;
+    /**
+     * Enable line numbers in code blocks
+     */
+    enableLineNumbers: boolean;
+    /**
+     * Custom CSS class for the container
+     */
+    containerClass: string;
+    /**
+     * Mermaid theme
+     */
+    mermaidTheme: 'default' | 'dark' | 'forest' | 'neutral' | 'base';
+    /**
+     * Whether to sanitize HTML output
+     */
+    sanitize: boolean;
+    /**
+     * Emitted when rendering is complete
+     */
+    rendered: EventEmitter<MarkdownRenderEvent>;
+    /**
+     * Emitted when a heading anchor is clicked
+     */
+    headingClick: EventEmitter<HeadingInfo>;
+    /**
+     * Emitted when code is copied to clipboard
+     */
+    codeCopied: EventEmitter<string>;
+    /**
+     * The sanitized HTML content to display
+     */
+    renderedContent: SafeHtml;
+    /**
+     * Public accessor for the component's element reference.
+     * Provided for backward compatibility with ngx-markdown API.
+     */
+    get element(): ElementRef<HTMLElement>;
+    private renderStartTime;
+    private hasMermaid;
+    private hasCodeBlocks;
+    constructor(elementRef: ElementRef<HTMLElement>, sanitizer: DomSanitizer, markdownService: MarkdownService, cdr: ChangeDetectorRef);
+    ngOnChanges(changes: SimpleChanges): void;
+    ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    /**
+     * Render the markdown content
+     */
+    private render;
+    /**
+     * Process rendered content after DOM update
+     * Handles syntax highlighting, mermaid rendering, copy buttons, etc.
+     */
+    private postRenderProcessing;
+    /**
+     * Setup collapsible sections by adding toggle buttons and click listeners
+     */
+    private setupCollapsibleListeners;
+    /**
+     * Create the expand/collapse all action buttons for sections with children
+     */
+    private createActionButtons;
+    /**
+     * Toggle a collapsible section
+     * @param section The section element to toggle
+     * @param toggle The toggle button element
+     */
+    private toggleSection;
+    /**
+     * Collapse all descendant sections (used by action button)
+     */
+    private collapseDescendants;
+    /**
+     * Expand all descendant sections (used by action button)
+     */
+    private expandDescendants;
+    /**
+     * Setup click listeners for heading anchors
+     */
+    private setupHeadingClickListeners;
+    /**
+     * Setup listeners to emit code copy events
+     */
+    private setupCodeCopyListeners;
+    /**
+     * Cleanup event listeners
+     */
+    private cleanupEventListeners;
+    /**
+     * Force a re-render of the markdown content
+     */
+    refresh(): void;
+    /**
+     * Get the current heading list (for TOC building)
+     */
+    getHeadings(): HeadingInfo[];
+    /**
+     * Scroll to a heading by ID
+     */
+    scrollToHeading(headingId: string): void;
+    /**
+     * Strip JavaScript from HTML content while preserving layout HTML.
+     * Removes <script> tags, on* event handlers, and javascript: URLs.
+     */
+    private stripJavaScript;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MarkdownComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MarkdownComponent, "mj-markdown", never, { "data": { "alias": "data"; "required": false; }; "enableHighlight": { "alias": "enableHighlight"; "required": false; }; "enableMermaid": { "alias": "enableMermaid"; "required": false; }; "enableCodeCopy": { "alias": "enableCodeCopy"; "required": false; }; "enableCollapsibleHeadings": { "alias": "enableCollapsibleHeadings"; "required": false; }; "collapsibleHeadingLevel": { "alias": "collapsibleHeadingLevel"; "required": false; }; "collapsibleDefaultExpanded": { "alias": "collapsibleDefaultExpanded"; "required": false; }; "autoExpandLevels": { "alias": "autoExpandLevels"; "required": false; }; "enableAlerts": { "alias": "enableAlerts"; "required": false; }; "enableSmartypants": { "alias": "enableSmartypants"; "required": false; }; "enableSvgRenderer": { "alias": "enableSvgRenderer"; "required": false; }; "enableHtml": { "alias": "enableHtml"; "required": false; }; "enableJavaScript": { "alias": "enableJavaScript"; "required": false; }; "enableHeadingIds": { "alias": "enableHeadingIds"; "required": false; }; "headingIdPrefix": { "alias": "headingIdPrefix"; "required": false; }; "enableLineNumbers": { "alias": "enableLineNumbers"; "required": false; }; "containerClass": { "alias": "containerClass"; "required": false; }; "mermaidTheme": { "alias": "mermaidTheme"; "required": false; }; "sanitize": { "alias": "sanitize"; "required": false; }; }, { "rendered": "rendered"; "headingClick": "headingClick"; "codeCopied": "codeCopied"; }, never, never, false, never>;
+}