@mzebley/mark-down-angular 1.0.0

package/README.md

@@ -0,0 +1,119 @@
+# mark↓ Angular Adapter
+*(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).
+
+## Table of contents
+
+1. [Installation](#installation)
+2. [Bootstrap configuration](#bootstrap-configuration)
+3. [Consuming snippets](#consuming-snippets)
+4. [`<snippet-view>` component](#snippet-view-component)
+5. [Server-side rendering](#server-side-rendering)
+6. [Testing tips](#testing-tips)
+7. [Roadmap](#roadmap)
+8. [Related packages](#related-packages)
+
+## Installation
+
+Install the Angular adapter alongside the core runtime:
+
+```bash
+npm install @mzebley/mark-down-angular @mzebley/mark-down
+```
+
+You will also need a manifest generated by the [CLI](../cli/README.md).
+
+## Bootstrap configuration
+
+Provide a shared `SnippetClient` from your root bootstrap call or feature module:
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideMarkDown } from '@mzebley/mark-down-angular';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    ...provideMarkDown({
+      manifest: '/snippets-index.json',
+    }),
+  ],
+});
+```
+
+`provideMarkDown` wires up the client as an Angular provider using the options you pass through. The manifest can be a URL, a factory, or a pre-fetched array—identical to the [core runtime options](../core/README.md#client-options).
+
+## Consuming snippets
+
+Inject `SnippetService` into components or services to access Observables for snippets:
+
+```ts
+import { Component, inject } from '@angular/core';
+import { SnippetService } from '@mzebley/mark-down-angular';
+
+@Component({
+  selector: 'docs-hero',
+  template: `
+    <ng-container *ngIf="hero$ | async as hero">
+      <h1>{{ hero.title }}</h1>
+      <div [innerHTML]="hero.html"></div>
+    </ng-container>
+  `,
+})
+export class DocsHeroComponent {
+  private readonly snippets = inject(SnippetService);
+  readonly hero$ = this.snippets.get('getting-started-welcome');
+}
+```
+
+The service mirrors the core client APIs (`get`, `list`, `listByType`, `listByGroup`) but returns cold Observables that share cached results across subscribers.
+
+## `<snippet-view>` component
+
+Render snippets declaratively with the bundled standalone component:
+
+```html
+<snippet-view [slug]="'components-button'" (loaded)="onSnippetLoaded($event)"></snippet-view>
+```
+
+Features:
+
+- Uses Angular's `DomSanitizer` to render HTML safely.
+- Emits a `loaded` event once the snippet resolves so parent components can react.
+- Provides built-in "Loading snippet…" and "Snippet not found" fallbacks (customize by wrapping the component or using the service directly).
+- Supports `class`/`ngClass` bindings for styling since it renders a standard `<div>`.
+
+## Server-side rendering
+
+When running in Angular Universal, supply a server-compatible fetch implementation:
+
+```ts
+import fetch from 'node-fetch';
+
+provideMarkDown({
+  manifest: () => import('../snippets-index.json'),
+  fetcher: (input, init) => fetch(input as string, init),
+});
+```
+
+The provider forwards all options to the underlying `SnippetClient`, so SSR and preloaded manifests work exactly like the core package.
+
+## Testing tips
+
+- Provide a mock manifest array during tests: `provideMarkDown({ manifest: mockManifest })`.
+- Use `SnippetService` with the Angular `TestBed` to assert filtering behaviour.
+- Pair with the [example application](../../examples/basic/README.md) to see how snippets integrate with routing and feature modules.
+
+## Roadmap
+
+- **Template primitives** – structural directives for rendering snippet lists via `*markDownSnippets`.
+- **AsyncPipe optimisations** – helpers that automatically unsubscribe / reuse cached Observables when using standalone components.
+- **Schematics** – Angular CLI generator for wiring `provideMarkDown` + `SnippetViewComponent`.
+- **SSR hydration helpers** – share manifest snapshots between server and browser to avoid double fetching.
+
+## Related packages
+
+- [Core runtime](../core/README.md)
+- [CLI](../cli/README.md)
+- [React adapter](../react/README.md)
+- [Project overview](../../README.md)

package/dist/index.cjs

@@ -0,0 +1,155 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from2, except, desc) => {
+  if (from2 && typeof from2 === "object" || typeof from2 === "function") {
+    for (let key of __getOwnPropNames(from2))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from2[key], enumerable: !(desc = __getOwnPropDesc(from2, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MARK_DOWN_CLIENT: () => MARK_DOWN_CLIENT,
+  MARK_DOWN_OPTIONS: () => MARK_DOWN_OPTIONS,
+  SnippetService: () => SnippetService,
+  SnippetViewComponent: () => SnippetViewComponent,
+  provideMarkDown: () => provideMarkDown
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/token.ts
+var import_core = require("@angular/core");
+var import_mark_down = require("@mzebley/mark-down");
+var MARK_DOWN_CLIENT = new import_core.InjectionToken("mark-down-client");
+var MARK_DOWN_OPTIONS = new import_core.InjectionToken("mark-down-options");
+function provideMarkDown(options, client) {
+  return [
+    { provide: MARK_DOWN_OPTIONS, useValue: options },
+    {
+      provide: MARK_DOWN_CLIENT,
+      useFactory: (opts) => client ?? new import_mark_down.SnippetClient(opts),
+      deps: [MARK_DOWN_OPTIONS]
+    }
+  ];
+}
+
+// src/snippet.service.ts
+var import_core2 = require("@angular/core");
+var import_rxjs = require("rxjs");
+var SnippetService = class {
+  constructor(client) {
+    this.client = client;
+  }
+  get(slug) {
+    return (0, import_rxjs.from)(this.client.get(slug)).pipe((0, import_rxjs.shareReplay)(1));
+  }
+  list(options) {
+    return (0, import_rxjs.from)(this.client.list(options)).pipe((0, import_rxjs.shareReplay)(1));
+  }
+  listByGroup(group, options) {
+    return (0, import_rxjs.from)(this.client.listByGroup(group, options)).pipe((0, import_rxjs.shareReplay)(1));
+  }
+  listByType(type, options) {
+    return (0, import_rxjs.from)(this.client.listByType(type, options)).pipe((0, import_rxjs.shareReplay)(1));
+  }
+  html(slug) {
+    return this.get(slug).pipe((0, import_rxjs.map)((snippet) => snippet?.html ?? null));
+  }
+};
+SnippetService = __decorateClass([
+  (0, import_core2.Injectable)({ providedIn: "root" }),
+  __decorateParam(0, (0, import_core2.Inject)(MARK_DOWN_CLIENT))
+], SnippetService);
+
+// src/snippet-view.component.ts
+var import_common = require("@angular/common");
+var import_core3 = require("@angular/core");
+var import_platform_browser = require("@angular/platform-browser");
+var import_rxjs2 = require("rxjs");
+var import_operators = require("rxjs/operators");
+var import_dompurify = __toESM(require("dompurify"), 1);
+var SnippetViewComponent = class {
+  constructor() {
+    this.slug$ = new import_rxjs2.BehaviorSubject(null);
+    this.sanitizer = (0, import_core3.inject)(import_platform_browser.DomSanitizer);
+    this.snippets = (0, import_core3.inject)(SnippetService);
+    this.loaded = new import_core3.EventEmitter();
+    this.snippet$ = this.slug$.pipe(
+      (0, import_operators.switchMap)((slug) => slug ? this.snippets.get(slug) : (0, import_rxjs2.of)(void 0)),
+      (0, import_operators.tap)((snippet) => this.loaded.emit(snippet)),
+      (0, import_operators.shareReplay)(1)
+    );
+    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);
+      })
+    );
+  }
+  ngOnChanges() {
+    this.slug$.next(this.slug ?? null);
+  }
+};
+__decorateClass([
+  (0, import_core3.Input)()
+], SnippetViewComponent.prototype, "slug", 2);
+__decorateClass([
+  (0, import_core3.Output)()
+], SnippetViewComponent.prototype, "loaded", 2);
+SnippetViewComponent = __decorateClass([
+  (0, import_core3.Component)({
+    selector: "snippet-view",
+    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>
+    <ng-template #loading>
+      <div class="mark-down-snippet--loading">Loading snippet\u2026</div>
+    </ng-template>
+  `,
+    changeDetection: import_core3.ChangeDetectionStrategy.OnPush
+  })
+], SnippetViewComponent);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MARK_DOWN_CLIENT,
+  MARK_DOWN_OPTIONS,
+  SnippetService,
+  SnippetViewComponent,
+  provideMarkDown
+});

package/dist/index.d.cts

@@ -0,0 +1,31 @@
+import { InjectionToken, Provider, OnChanges, EventEmitter } from '@angular/core';
+import { SnippetClient, SnippetClientOptions, Snippet, ListOptions, SnippetMeta } from '@mzebley/mark-down';
+import { Observable } from 'rxjs';
+import { SafeHtml } from '@angular/platform-browser';
+
+declare const MARK_DOWN_CLIENT: InjectionToken<SnippetClient>;
+declare const MARK_DOWN_OPTIONS: InjectionToken<SnippetClientOptions>;
+declare function provideMarkDown(options: SnippetClientOptions, client?: SnippetClient): Provider[];
+
+declare class SnippetService {
+    private readonly client;
+    constructor(client: SnippetClient);
+    get(slug: string): Observable<Snippet | undefined>;
+    list(options?: ListOptions): Observable<SnippetMeta[]>;
+    listByGroup(group: string, options?: ListOptions): Observable<SnippetMeta[]>;
+    listByType(type: string, options?: ListOptions): Observable<SnippetMeta[]>;
+    html(slug: string): Observable<string | null>;
+}
+
+declare class SnippetViewComponent implements OnChanges {
+    private readonly slug$;
+    private readonly sanitizer;
+    private readonly snippets;
+    slug?: string;
+    readonly loaded: EventEmitter<Snippet | undefined>;
+    private readonly snippet$;
+    readonly content$: Observable<SafeHtml | null>;
+    ngOnChanges(): void;
+}
+
+export { MARK_DOWN_CLIENT, MARK_DOWN_OPTIONS, SnippetService, SnippetViewComponent, provideMarkDown };

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { InjectionToken, Provider, OnChanges, EventEmitter } from '@angular/core';
+import { SnippetClient, SnippetClientOptions, Snippet, ListOptions, SnippetMeta } from '@mzebley/mark-down';
+import { Observable } from 'rxjs';
+import { SafeHtml } from '@angular/platform-browser';
+
+declare const MARK_DOWN_CLIENT: InjectionToken<SnippetClient>;
+declare const MARK_DOWN_OPTIONS: InjectionToken<SnippetClientOptions>;
+declare function provideMarkDown(options: SnippetClientOptions, client?: SnippetClient): Provider[];
+
+declare class SnippetService {
+    private readonly client;
+    constructor(client: SnippetClient);
+    get(slug: string): Observable<Snippet | undefined>;
+    list(options?: ListOptions): Observable<SnippetMeta[]>;
+    listByGroup(group: string, options?: ListOptions): Observable<SnippetMeta[]>;
+    listByType(type: string, options?: ListOptions): Observable<SnippetMeta[]>;
+    html(slug: string): Observable<string | null>;
+}
+
+declare class SnippetViewComponent implements OnChanges {
+    private readonly slug$;
+    private readonly sanitizer;
+    private readonly snippets;
+    slug?: string;
+    readonly loaded: EventEmitter<Snippet | undefined>;
+    private readonly snippet$;
+    readonly content$: Observable<SafeHtml | null>;
+    ngOnChanges(): void;
+}
+
+export { MARK_DOWN_CLIENT, MARK_DOWN_OPTIONS, SnippetService, SnippetViewComponent, provideMarkDown };

package/dist/index.js

@@ -0,0 +1,124 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/token.ts
+import { InjectionToken } from "@angular/core";
+import { SnippetClient } from "@mzebley/mark-down";
+var MARK_DOWN_CLIENT = new InjectionToken("mark-down-client");
+var MARK_DOWN_OPTIONS = new InjectionToken("mark-down-options");
+function provideMarkDown(options, client) {
+  return [
+    { provide: MARK_DOWN_OPTIONS, useValue: options },
+    {
+      provide: MARK_DOWN_CLIENT,
+      useFactory: (opts) => client ?? new SnippetClient(opts),
+      deps: [MARK_DOWN_OPTIONS]
+    }
+  ];
+}
+
+// src/snippet.service.ts
+import { Inject, Injectable } from "@angular/core";
+import { from, map, shareReplay } from "rxjs";
+var SnippetService = class {
+  constructor(client) {
+    this.client = client;
+  }
+  get(slug) {
+    return from(this.client.get(slug)).pipe(shareReplay(1));
+  }
+  list(options) {
+    return from(this.client.list(options)).pipe(shareReplay(1));
+  }
+  listByGroup(group, options) {
+    return from(this.client.listByGroup(group, options)).pipe(shareReplay(1));
+  }
+  listByType(type, options) {
+    return from(this.client.listByType(type, options)).pipe(shareReplay(1));
+  }
+  html(slug) {
+    return this.get(slug).pipe(map((snippet) => snippet?.html ?? null));
+  }
+};
+SnippetService = __decorateClass([
+  Injectable({ providedIn: "root" }),
+  __decorateParam(0, Inject(MARK_DOWN_CLIENT))
+], SnippetService);
+
+// src/snippet-view.component.ts
+import { CommonModule } from "@angular/common";
+import {
+  ChangeDetectionStrategy,
+  Component,
+  EventEmitter,
+  Input,
+  Output,
+  inject
+} from "@angular/core";
+import { DomSanitizer } from "@angular/platform-browser";
+import { BehaviorSubject, of } from "rxjs";
+import { map as map2, shareReplay as shareReplay2, switchMap, tap } from "rxjs/operators";
+import DOMPurify from "dompurify";
+var SnippetViewComponent = class {
+  constructor() {
+    this.slug$ = new BehaviorSubject(null);
+    this.sanitizer = inject(DomSanitizer);
+    this.snippets = inject(SnippetService);
+    this.loaded = new EventEmitter();
+    this.snippet$ = this.slug$.pipe(
+      switchMap((slug) => slug ? this.snippets.get(slug) : of(void 0)),
+      tap((snippet) => this.loaded.emit(snippet)),
+      shareReplay2(1)
+    );
+    this.content$ = this.snippet$.pipe(
+      map2((snippet) => {
+        if (!snippet) {
+          return null;
+        }
+        const sanitized = DOMPurify.sanitize(snippet.html);
+        return this.sanitizer.bypassSecurityTrustHtml(sanitized);
+      })
+    );
+  }
+  ngOnChanges() {
+    this.slug$.next(this.slug ?? null);
+  }
+};
+__decorateClass([
+  Input()
+], SnippetViewComponent.prototype, "slug", 2);
+__decorateClass([
+  Output()
+], SnippetViewComponent.prototype, "loaded", 2);
+SnippetViewComponent = __decorateClass([
+  Component({
+    selector: "snippet-view",
+    standalone: true,
+    imports: [CommonModule],
+    template: `
+    <ng-container *ngIf="content$ | async as html; else loading">
+      <div class="mark-down-snippet" [innerHTML]="html"></div>
+    </ng-container>
+    <ng-template #loading>
+      <div class="mark-down-snippet--loading">Loading snippet\u2026</div>
+    </ng-template>
+  `,
+    changeDetection: ChangeDetectionStrategy.OnPush
+  })
+], SnippetViewComponent);
+export {
+  MARK_DOWN_CLIENT,
+  MARK_DOWN_OPTIONS,
+  SnippetService,
+  SnippetViewComponent,
+  provideMarkDown
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@mzebley/mark-down-angular",
+  "version": "1.0.0",
+  "description": "mark↓ Angular Adapter",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --dts --format esm,cjs"
+  },
+  "dependencies": {
+    "@mzebley/mark-down": "file:../core",
+    "dompurify": "^3.0.9"
+  },
+  "peerDependencies": {
+    "@angular/common": "^17.0.0",
+    "@angular/core": "^17.0.0",
+    "@angular/platform-browser": "^17.0.0",
+    "rxjs": "^7.8.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./token";
+export * from "./snippet.service";
+export * from "./snippet-view.component";

package/src/snippet-view.component.ts

@@ -0,0 +1,59 @@
+import { CommonModule } from "@angular/common";
+import {
+  ChangeDetectionStrategy,
+  Component,
+  EventEmitter,
+  Input,
+  OnChanges,
+  Output,
+  inject
+} from "@angular/core";
+import { DomSanitizer, SafeHtml } from "@angular/platform-browser";
+import { BehaviorSubject, Observable, of } from "rxjs";
+import { map, shareReplay, switchMap, tap } from "rxjs/operators";
+import type { Snippet } from "@mzebley/mark-down";
+import { SnippetService } from "./snippet.service";
+import DOMPurify from "dompurify";
+
+@Component({
+  selector: "snippet-view",
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <ng-container *ngIf="content$ | async as html; else loading">
+      <div class="mark-down-snippet" [innerHTML]="html"></div>
+    </ng-container>
+    <ng-template #loading>
+      <div class="mark-down-snippet--loading">Loading snippet…</div>
+    </ng-template>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class SnippetViewComponent implements OnChanges {
+  private readonly slug$ = new BehaviorSubject<string | null>(null);
+  private readonly sanitizer = inject(DomSanitizer);
+  private readonly snippets = inject(SnippetService);
+
+  @Input() slug?: string;
+  @Output() readonly loaded = new EventEmitter<Snippet | undefined>();
+
+  private readonly snippet$: Observable<Snippet | undefined> = this.slug$.pipe(
+    switchMap((slug) => (slug ? this.snippets.get(slug) : of(undefined))),
+    tap((snippet) => this.loaded.emit(snippet)),
+    shareReplay(1)
+  );
+
+  readonly content$: Observable<SafeHtml | null> = this.snippet$.pipe(
+    map((snippet) => {
+      if (!snippet) {
+        return null;
+      }
+      const sanitized = DOMPurify.sanitize(snippet.html);
+      return this.sanitizer.bypassSecurityTrustHtml(sanitized);
+    })
+  );
+
+  ngOnChanges(): void {
+    this.slug$.next(this.slug ?? null);
+  }
+}

package/src/snippet.service.ts

@@ -0,0 +1,30 @@
+import { Inject, Injectable } from "@angular/core";
+import { from, map, Observable, shareReplay } from "rxjs";
+import type { ListOptions, Snippet, SnippetMeta } from "@mzebley/mark-down";
+import { SnippetClient } from "@mzebley/mark-down";
+import { MARK_DOWN_CLIENT } from "./token";
+
+@Injectable({ providedIn: "root" })
+export class SnippetService {
+  constructor(@Inject(MARK_DOWN_CLIENT) private readonly client: SnippetClient) {}
+
+  get(slug: string): Observable<Snippet | undefined> {
+    return from(this.client.get(slug)).pipe(shareReplay(1));
+  }
+
+  list(options?: ListOptions): Observable<SnippetMeta[]> {
+    return from(this.client.list(options)).pipe(shareReplay(1));
+  }
+
+  listByGroup(group: string, options?: ListOptions): Observable<SnippetMeta[]> {
+    return from(this.client.listByGroup(group, options)).pipe(shareReplay(1));
+  }
+
+  listByType(type: string, options?: ListOptions): Observable<SnippetMeta[]> {
+    return from(this.client.listByType(type, options)).pipe(shareReplay(1));
+  }
+
+  html(slug: string): Observable<string | null> {
+    return this.get(slug).pipe(map((snippet) => snippet?.html ?? null));
+  }
+}

package/src/token.ts

@@ -0,0 +1,16 @@
+import { InjectionToken, Provider } from "@angular/core";
+import { SnippetClient, type SnippetClientOptions } from "@mzebley/mark-down";
+
+export const MARK_DOWN_CLIENT = new InjectionToken<SnippetClient>("mark-down-client");
+export const MARK_DOWN_OPTIONS = new InjectionToken<SnippetClientOptions>("mark-down-options");
+
+export function provideMarkDown(options: SnippetClientOptions, client?: SnippetClient): Provider[] {
+  return [
+    { provide: MARK_DOWN_OPTIONS, useValue: options },
+    {
+      provide: MARK_DOWN_CLIENT,
+      useFactory: (opts: SnippetClientOptions) => client ?? new SnippetClient(opts),
+      deps: [MARK_DOWN_OPTIONS]
+    }
+  ];
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src/**/*"]
+}