@mzebley/mark-down-angular 1.2.2 → 1.2.4

package/README.md

@@ -1,5 +1,6 @@
 # mark↓ Angular Adapter
-*(published as `@mzebley/mark-down-angular`)*
+
+_(published as `@mzebley/mark-down-angular`)_
 
 Angular bindings for the [mark↓ core runtime](../core/README.md). This package wraps `SnippetClient` with Angular-friendly providers, services, and components so you can render Markdown snippets safely inside your application. For background on the monorepo, see the [root README](../../README.md).
 
@@ -29,14 +30,14 @@ You will also need a manifest generated by the [CLI](../cli/README.md).
 Provide a shared `SnippetClient` from your root bootstrap call or feature module:
 
 ```ts
-import { bootstrapApplication } from '@angular/platform-browser';
-import { provideSnippetClient } from '@mzebley/mark-down/angular';
+import { bootstrapApplication } from "@angular/platform-browser";
+import { provideSnippetClient } from "@mzebley/mark-down/angular";
 
 bootstrapApplication(AppComponent, {
   providers: [
     ...provideSnippetClient({
-      manifest: '/assets/content/snippets/manifest.json',
-      base: '/assets/content/snippets',
+      manifest: "/assets/content/snippets/manifest.json",
+      base: "/assets/content/snippets",
     }),
   ],
 });
@@ -46,12 +47,12 @@ bootstrapApplication(AppComponent, {
 
 ### Angular compatibility
 
-| Angular version | Status |
-| ---------------- | ------ |
-| 17.x             | ✅ Supported |
-| 18.x             | ✅ Supported |
-| 19.x             | ✅ Supported |
-| 20.x             | ✅ Supported |
+| Angular version | Status       |
+| --------------- | ------------ |
+| 17.x            | ✅ Supported |
+| 18.x            | ✅ Supported |
+| 19.x            | ✅ Supported |
+| 20.x            | ✅ Supported |
 
 The package declares peer dependency ranges `>=17 <21` so projects running any currently supported Angular major release can install without `--legacy-peer-deps`.
 
@@ -60,11 +61,11 @@ The package declares peer dependency ranges `>=17 <21` so projects running any c
 Inject `MarkdownSnippetService` into components or services to access Observables for snippets:
 
 ```ts
-import { Component, inject } from '@angular/core';
-import { MarkdownSnippetService } from '@mzebley/mark-down/angular';
+import { Component, inject } from "@angular/core";
+import { MarkdownSnippetService } from "@mzebley/mark-down/angular";
 
 @Component({
-  selector: 'docs-hero',
+  selector: "docs-hero",
   template: `
     <ng-container *ngIf="hero$ | async as hero">
       <h1>{{ hero.title }}</h1>
@@ -74,7 +75,7 @@ import { MarkdownSnippetService } from '@mzebley/mark-down/angular';
 })
 export class DocsHeroComponent {
   private readonly snippets = inject(MarkdownSnippetService);
-  readonly hero$ = this.snippets.get('getting-started-welcome');
+  readonly hero$ = this.snippets.get("getting-started-welcome");
 }
 ```
 
@@ -85,31 +86,42 @@ The service mirrors the core client APIs (`get`, `listAll`, `listByType`, `listB
 Render snippets declaratively with the bundled standalone component:
 
 ```html
-<snippet-view [slug]="'components-button'" (loaded)="onSnippetLoaded($event)"></snippet-view>
+<snippet-view
+  [slug]="'components-button'"
+  (loaded)="onSnippetLoaded($event)"
+></snippet-view>
 ```
 
 Features:
 
-- Uses Angular's `DomSanitizer` to render HTML safely.
+- Uses Angular's `DomSanitizer` for trusted HTML binding and DOMPurify in browser rendering.
 - Emits a `loaded` event once the snippet resolves so parent components can react.
 - Provides a loading placeholder and gracefully emits `undefined` when the slug cannot be resolved.
 - Supports `class`/`ngClass` bindings for styling since it renders a standard `<div>`.
 
+### Security warning
+
+The Angular adapter is intentionally compatible with untrusted/unsanitized snippet pipelines. That flexibility is a feature, but it means you must decide where sanitization happens:
+
+- For untrusted content, sanitize in `SnippetClient` (`sanitize` option) and/or during build with `mark-down compile-page --sanitize`.
+- If sanitization is disabled, snippet HTML is treated as trusted and may include dangerous markup.
+
 ## Server-side rendering
 
 When running in Angular Universal, supply a server-compatible fetch implementation:
 
 ```ts
-import fetch from 'node-fetch';
+import fetch from "node-fetch";
 
 provideSnippetClient({
-  manifest: () => import('../snippets-index.json'),
-  fetch: (url) => fetch(url).then((response) => {
-    if (!response.ok) {
-      throw new Error(`Request failed with status ${response.status}`);
-    }
-    return response;
-  }),
+  manifest: () => import("../snippets-index.json"),
+  fetch: (url) =>
+    fetch(url).then((response) => {
+      if (!response.ok) {
+        throw new Error(`Request failed with status ${response.status}`);
+      }
+      return response;
+    }),
 });
 ```
 

package/dist/index.cjs

@@ -72,26 +72,45 @@ var SnippetViewComponent = class {
     this.sanitizer = (0, import_core.inject)(import_platform_browser.DomSanitizer);
     this.snippets = (0, import_core.inject)(import_angular2.MarkdownSnippetService);
     this.loaded = new import_core.EventEmitter();
-    this.snippet$ = this.slug$.pipe(
+    this.state$ = this.slug$.pipe(
       (0, import_operators.switchMap)(
-        (slug) => slug ? this.snippets.get(slug).pipe((0, import_operators.catchError)(() => (0, import_rxjs.of)(null))) : (0, import_rxjs.of)(null)
+        (slug) => slug ? this.snippets.get(slug).pipe(
+          (0, import_operators.map)((snippet) => ({ loading: false, error: false, snippet })),
+          (0, import_operators.catchError)(
+            () => (0, import_rxjs.of)({ loading: false, error: true, snippet: null })
+          ),
+          (0, import_operators.startWith)({ loading: true, error: false, snippet: null })
+        ) : (0, import_rxjs.of)({ loading: false, error: false, snippet: null })
       ),
-      (0, import_operators.tap)((snippet) => this.loaded.emit(snippet ?? void 0)),
+      (0, import_operators.tap)((state) => {
+        if (!state.loading) {
+          this.loaded.emit(state.snippet ?? void 0);
+        }
+      }),
+      (0, import_operators.map)((state) => ({
+        loading: state.loading,
+        error: state.error,
+        html: this.toSafeHtml(state.snippet)
+      })),
       (0, import_operators.shareReplay)({ bufferSize: 1, refCount: true })
     );
-    this.content$ = this.snippet$.pipe(
-      (0, import_operators.map)((snippet) => {
-        if (!snippet) {
-          return null;
-        }
-        const sanitized = import_dompurify.default.sanitize(snippet.html);
-        return this.sanitizer.bypassSecurityTrustHtml(sanitized);
-      })
+    this.content$ = this.state$.pipe(
+      (0, import_operators.map)((state) => state.html)
     );
   }
   ngOnChanges() {
     this.slug$.next(this.slug ?? null);
   }
+  toSafeHtml(snippet) {
+    if (!snippet) {
+      return null;
+    }
+    if (typeof window === "undefined") {
+      return this.sanitizer.bypassSecurityTrustHtml(snippet.html);
+    }
+    const sanitized = import_dompurify.default.sanitize(snippet.html);
+    return this.sanitizer.bypassSecurityTrustHtml(sanitized);
+  }
 };
 __decorateClass([
   (0, import_core.Input)()
@@ -105,12 +124,25 @@ SnippetViewComponent = __decorateClass([
     standalone: true,
     imports: [import_common.CommonModule],
     template: `
-    <ng-container *ngIf="content$ | async as html; else loading">
-      <div class="mark-down-snippet" [innerHTML]="html"></div>
+    <ng-container *ngIf="state$ | async as state">
+      <div *ngIf="state.loading" class="mark-down-snippet--loading">
+        Loading snippet\u2026
+      </div>
+      <div *ngIf="!state.loading && state.error" class="mark-down-snippet--error">
+        Unable to load snippet.
+      </div>
+      <div
+        *ngIf="!state.loading && !state.error && state.html !== null"
+        class="mark-down-snippet"
+        [innerHTML]="state.html"
+      ></div>
+      <div
+        *ngIf="!state.loading && !state.error && state.html === null"
+        class="mark-down-snippet--empty"
+      >
+        Snippet not found.
+      </div>
     </ng-container>
-    <ng-template #loading>
-      <div class="mark-down-snippet--loading">Loading snippet\u2026</div>
-    </ng-template>
   `,
     changeDetection: import_core.ChangeDetectionStrategy.OnPush
   })

package/dist/index.d.cts

@@ -18,9 +18,14 @@ declare class SnippetViewComponent implements OnChanges {
     private readonly snippets;
     slug?: string;
     readonly loaded: EventEmitter<Snippet | undefined>;
-    private readonly snippet$;
+    readonly state$: Observable<{
+        loading: boolean;
+        error: boolean;
+        html: SafeHtml | null;
+    }>;
     readonly content$: Observable<SafeHtml | null>;
     ngOnChanges(): void;
+    private toSafeHtml;
 }
 
 export { MARK_DOWN_CLIENT, MARK_DOWN_OPTIONS, SnippetViewComponent, provideMarkDown };

package/dist/index.d.ts

@@ -18,9 +18,14 @@ declare class SnippetViewComponent implements OnChanges {
     private readonly snippets;
     slug?: string;
     readonly loaded: EventEmitter<Snippet | undefined>;
-    private readonly snippet$;
+    readonly state$: Observable<{
+        loading: boolean;
+        error: boolean;
+        html: SafeHtml | null;
+    }>;
     readonly content$: Observable<SafeHtml | null>;
     ngOnChanges(): void;
+    private toSafeHtml;
 }
 
 export { MARK_DOWN_CLIENT, MARK_DOWN_OPTIONS, SnippetViewComponent, provideMarkDown };

package/dist/index.js

@@ -39,7 +39,14 @@ import {
 } from "@angular/core";
 import { DomSanitizer } from "@angular/platform-browser";
 import { BehaviorSubject, of } from "rxjs";
-import { catchError, map, shareReplay, switchMap, tap } from "rxjs/operators";
+import {
+  catchError,
+  map,
+  shareReplay,
+  startWith,
+  switchMap,
+  tap
+} from "rxjs/operators";
 import DOMPurify from "dompurify";
 var SnippetViewComponent = class {
   constructor() {
@@ -47,26 +54,45 @@ var SnippetViewComponent = class {
     this.sanitizer = inject(DomSanitizer);
     this.snippets = inject(MarkdownSnippetService);
     this.loaded = new EventEmitter();
-    this.snippet$ = this.slug$.pipe(
+    this.state$ = this.slug$.pipe(
       switchMap(
-        (slug) => slug ? this.snippets.get(slug).pipe(catchError(() => of(null))) : of(null)
+        (slug) => slug ? this.snippets.get(slug).pipe(
+          map((snippet) => ({ loading: false, error: false, snippet })),
+          catchError(
+            () => of({ loading: false, error: true, snippet: null })
+          ),
+          startWith({ loading: true, error: false, snippet: null })
+        ) : of({ loading: false, error: false, snippet: null })
       ),
-      tap((snippet) => this.loaded.emit(snippet ?? void 0)),
+      tap((state) => {
+        if (!state.loading) {
+          this.loaded.emit(state.snippet ?? void 0);
+        }
+      }),
+      map((state) => ({
+        loading: state.loading,
+        error: state.error,
+        html: this.toSafeHtml(state.snippet)
+      })),
       shareReplay({ bufferSize: 1, refCount: true })
     );
-    this.content$ = this.snippet$.pipe(
-      map((snippet) => {
-        if (!snippet) {
-          return null;
-        }
-        const sanitized = DOMPurify.sanitize(snippet.html);
-        return this.sanitizer.bypassSecurityTrustHtml(sanitized);
-      })
+    this.content$ = this.state$.pipe(
+      map((state) => state.html)
     );
   }
   ngOnChanges() {
     this.slug$.next(this.slug ?? null);
   }
+  toSafeHtml(snippet) {
+    if (!snippet) {
+      return null;
+    }
+    if (typeof window === "undefined") {
+      return this.sanitizer.bypassSecurityTrustHtml(snippet.html);
+    }
+    const sanitized = DOMPurify.sanitize(snippet.html);
+    return this.sanitizer.bypassSecurityTrustHtml(sanitized);
+  }
 };
 __decorateClass([
   Input()
@@ -80,12 +106,25 @@ SnippetViewComponent = __decorateClass([
     standalone: true,
     imports: [CommonModule],
     template: `
-    <ng-container *ngIf="content$ | async as html; else loading">
-      <div class="mark-down-snippet" [innerHTML]="html"></div>
+    <ng-container *ngIf="state$ | async as state">
+      <div *ngIf="state.loading" class="mark-down-snippet--loading">
+        Loading snippet\u2026
+      </div>
+      <div *ngIf="!state.loading && state.error" class="mark-down-snippet--error">
+        Unable to load snippet.
+      </div>
+      <div
+        *ngIf="!state.loading && !state.error && state.html !== null"
+        class="mark-down-snippet"
+        [innerHTML]="state.html"
+      ></div>
+      <div
+        *ngIf="!state.loading && !state.error && state.html === null"
+        class="mark-down-snippet--empty"
+      >
+        Snippet not found.
+      </div>
     </ng-container>
-    <ng-template #loading>
-      <div class="mark-down-snippet--loading">Loading snippet\u2026</div>
-    </ng-template>
   `,
     changeDetection: ChangeDetectionStrategy.OnPush
   })

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@mzebley/mark-down-angular",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "mark↓ Angular Adapter",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -24,6 +26,9 @@
     "@mzebley/mark-down": "^1.2.2",
     "dompurify": "^3.0.9"
   },
+  "devDependencies": {
+    "@angular/platform-browser": ">=17 <21"
+  },
   "peerDependencies": {
     "@angular/common": ">=17 <21",
     "@angular/core": ">=17 <21",