@mzebley/mark-down-react 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# mark↓ React Adapter
+*(published as `@mzebley/mark-down-react`)*
+
+React bindings for the [mark↓ core runtime](../core/README.md). This package exposes context providers, hooks, and ready-to-use components that make it simple to render Markdown snippets safely. For a broader overview of the project, start with the [root README](../../README.md).
+
+## Table of contents
+
+1. [Installation](#installation)
+2. [Provider setup](#provider-setup)
+3. [Hook](#hook)
+4. [`<SnippetView />` component](#snippetview--component)
+5. [Server-side rendering](#server-side-rendering)
+6. [TypeScript helpers](#typescript-helpers)
+7. [Roadmap](#roadmap)
+8. [Related packages](#related-packages)
+
+## Installation
+
+Install the adapter along with the core runtime and DOMPurify (used for sanitising HTML):
+
+```bash
+npm install @mzebley/mark-down-react @mzebley/mark-down dompurify
+```
+
+Generate a manifest with the [CLI](../cli/README.md) before rendering snippets.
+
+## Provider setup
+
+Wrap your app with the `SnippetProvider` so that hooks and components can access a shared client instance:
+
+```tsx
+import { SnippetProvider } from '@mzebley/mark-down-react';
+
+export function App({ children }: { children: React.ReactNode }) {
+  return (
+    <SnippetProvider options={{ manifest: '/snippets-index.json' }}>
+      {children}
+    </SnippetProvider>
+  );
+}
+```
+
+`options` maps directly to the [`SnippetClient` configuration](../core/README.md#client-options), so you can provide custom fetchers, renderers, or manifest loaders as needed.
+
+## Hook
+
+### `useSnippet(slug)`
+
+Fetch a single snippet and track loading / error state:
+
+```tsx
+import { useSnippet } from '@mzebley/mark-down-react';
+
+export function Hero() {
+  const { snippet, loading, error } = useSnippet('getting-started-welcome');
+
+  if (loading) return <p>Loading…</p>;
+  if (error) return <p role="alert">Failed to load snippet.</p>;
+  if (!snippet) return null;
+
+  return <div dangerouslySetInnerHTML={{ __html: snippet.html }} />;
+}
+```
+
+## `<SnippetView />` component
+
+Render snippets declaratively with built-in loading and error fallbacks:
+
+```tsx
+import { SnippetView } from '@mzebley/mark-down-react';
+
+<SnippetView
+  slug="components-button"
+  loadingFallback={<p>Loading…</p>}
+  errorFallback={<p role="alert">Unable to load snippet.</p>}
+  onLoaded={(snippet) => console.log('Rendered', snippet.slug)}
+/>;
+```
+
+Features:
+
+- Uses DOMPurify under the hood for HTML sanitisation.
+- Accepts `className` for styling and emits `onLoaded(snippet)` once HTML resolves.
+- Customise UX via `loadingFallback` / `errorFallback`, or render the hook directly for complete control.
+
+## Server-side rendering
+
+When using Next.js, Remix, or another SSR framework, provide a server-safe fetch implementation:
+
+```tsx
+import fetch from 'node-fetch';
+import { SnippetProvider } from '@mzebley/mark-down-react';
+
+<SnippetProvider
+  options={{
+    manifest: () => import('../snippets-index.json'),
+    fetcher: (input, init) => fetch(input as string, init),
+  }}
+>
+  {children}
+</SnippetProvider>;
+```
+
+Because the adapter defers to the core runtime, SSR works the same way as the base client. Pair with framework-specific data fetching if you prefer to prehydrate snippets.
+
+## TypeScript helpers
+
+All exported hooks and components ship with rich TypeScript definitions:
+
+- Use the `Snippet` and `SnippetMeta` types from `@mzebley/mark-down` to annotate props.
+- Narrow snippet metadata with generics: `useSnippet<CustomExtra>('slug')`.
+- Leverage the `SnippetContextValue` interface when mocking providers in tests.
+
+## Roadmap
+
+- **Collection hooks** – add `useSnippets` for list queries and pagination helpers for design system docs.
+- **Suspense support** – optional wrappers that expose a resource-style API for React 18 concurrent features.
+- **Custom sanitizers** – let consumers inject DOMPurify configs or alternate HTML sanitizers.
+- **Storybook plugin** – surface snippets inside Storybook/Chromatic panels for quick previews.
+
+## Related packages
+
+- [Core runtime](../core/README.md)
+- [CLI](../cli/README.md)
+- [Angular adapter](../angular/README.md)
+- [Example app](../../examples/basic/README.md)
+- [Monorepo overview](../../README.md)

package/dist/index.cjs

@@ -0,0 +1,126 @@
+"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, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, 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);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SnippetProvider: () => SnippetProvider,
+  SnippetView: () => SnippetView,
+  useSnippet: () => useSnippet,
+  useSnippetClient: () => useSnippetClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/context.tsx
+var import_react = require("react");
+var import_mark_down = require("@mzebley/mark-down");
+var import_jsx_runtime = require("react/jsx-runtime");
+var SnippetClientContext = (0, import_react.createContext)(null);
+function SnippetProvider({ client, options, children }) {
+  const value = (0, import_react.useMemo)(() => {
+    if (client) {
+      return client;
+    }
+    if (options) {
+      return new import_mark_down.SnippetClient(options);
+    }
+    throw new Error("SnippetProvider requires either a client or options");
+  }, [client, options]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SnippetClientContext.Provider, { value, children });
+}
+function useSnippetClient() {
+  const client = (0, import_react.useContext)(SnippetClientContext);
+  if (!client) {
+    throw new Error("useSnippetClient must be used within a SnippetProvider");
+  }
+  return client;
+}
+
+// src/hooks.ts
+var import_react2 = require("react");
+function useSnippet(slug) {
+  const client = useSnippetClient();
+  const [result, setResult] = (0, import_react2.useState)(() => ({
+    loading: Boolean(slug)
+  }));
+  (0, import_react2.useEffect)(() => {
+    if (!slug) {
+      setResult({ loading: false });
+      return;
+    }
+    let cancelled = false;
+    setResult((prev) => ({ ...prev, loading: true, error: void 0 }));
+    client.get(slug).then((snippet) => {
+      if (cancelled) return;
+      setResult({ snippet, loading: false });
+    }).catch((error) => {
+      if (cancelled) return;
+      setResult({ loading: false, error });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [client, slug]);
+  return result;
+}
+
+// src/snippet-view.tsx
+var import_react3 = require("react");
+var import_dompurify = __toESM(require("dompurify"), 1);
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function SnippetView({
+  slug,
+  className,
+  loadingFallback = "Loading\u2026",
+  errorFallback = "Unable to load snippet",
+  onLoaded
+}) {
+  const state = useSnippet(slug);
+  const safeHtml = (0, import_react3.useMemo)(() => state.snippet ? import_dompurify.default.sanitize(state.snippet.html) : void 0, [state.snippet]);
+  (0, import_react3.useEffect)(() => {
+    onLoaded?.(state.snippet);
+  }, [state.snippet, onLoaded]);
+  if (state.loading) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className, children: loadingFallback });
+  }
+  if (state.error) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className, children: errorFallback });
+  }
+  if (!state.snippet) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className, children: "Snippet not found" });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className, dangerouslySetInnerHTML: { __html: safeHtml ?? "" } });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SnippetProvider,
+  SnippetView,
+  useSnippet,
+  useSnippetClient
+});

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { SnippetClient, SnippetClientOptions, Snippet } from '@mzebley/mark-down';
+
+interface SnippetProviderProps {
+    client?: SnippetClient;
+    options?: SnippetClientOptions;
+    children: ReactNode;
+}
+declare function SnippetProvider({ client, options, children }: SnippetProviderProps): react_jsx_runtime.JSX.Element;
+declare function useSnippetClient(): SnippetClient;
+
+interface UseSnippetResult {
+    snippet?: Snippet;
+    loading: boolean;
+    error?: Error;
+}
+declare function useSnippet(slug?: string | null): UseSnippetResult;
+
+interface SnippetViewProps {
+    slug: string;
+    className?: string;
+    loadingFallback?: ReactNode;
+    errorFallback?: ReactNode;
+    onLoaded?: (snippet?: Snippet) => void;
+}
+declare function SnippetView({ slug, className, loadingFallback, errorFallback, onLoaded }: SnippetViewProps): react_jsx_runtime.JSX.Element;
+
+export { SnippetProvider, type SnippetProviderProps, SnippetView, type SnippetViewProps, type UseSnippetResult, useSnippet, useSnippetClient };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { SnippetClient, SnippetClientOptions, Snippet } from '@mzebley/mark-down';
+
+interface SnippetProviderProps {
+    client?: SnippetClient;
+    options?: SnippetClientOptions;
+    children: ReactNode;
+}
+declare function SnippetProvider({ client, options, children }: SnippetProviderProps): react_jsx_runtime.JSX.Element;
+declare function useSnippetClient(): SnippetClient;
+
+interface UseSnippetResult {
+    snippet?: Snippet;
+    loading: boolean;
+    error?: Error;
+}
+declare function useSnippet(slug?: string | null): UseSnippetResult;
+
+interface SnippetViewProps {
+    slug: string;
+    className?: string;
+    loadingFallback?: ReactNode;
+    errorFallback?: ReactNode;
+    onLoaded?: (snippet?: Snippet) => void;
+}
+declare function SnippetView({ slug, className, loadingFallback, errorFallback, onLoaded }: SnippetViewProps): react_jsx_runtime.JSX.Element;
+
+export { SnippetProvider, type SnippetProviderProps, SnippetView, type SnippetViewProps, type UseSnippetResult, useSnippet, useSnippetClient };

package/dist/index.js

@@ -0,0 +1,86 @@
+// src/context.tsx
+import { createContext, useContext, useMemo } from "react";
+import { SnippetClient } from "@mzebley/mark-down";
+import { jsx } from "react/jsx-runtime";
+var SnippetClientContext = createContext(null);
+function SnippetProvider({ client, options, children }) {
+  const value = useMemo(() => {
+    if (client) {
+      return client;
+    }
+    if (options) {
+      return new SnippetClient(options);
+    }
+    throw new Error("SnippetProvider requires either a client or options");
+  }, [client, options]);
+  return /* @__PURE__ */ jsx(SnippetClientContext.Provider, { value, children });
+}
+function useSnippetClient() {
+  const client = useContext(SnippetClientContext);
+  if (!client) {
+    throw new Error("useSnippetClient must be used within a SnippetProvider");
+  }
+  return client;
+}
+
+// src/hooks.ts
+import { useEffect, useState } from "react";
+function useSnippet(slug) {
+  const client = useSnippetClient();
+  const [result, setResult] = useState(() => ({
+    loading: Boolean(slug)
+  }));
+  useEffect(() => {
+    if (!slug) {
+      setResult({ loading: false });
+      return;
+    }
+    let cancelled = false;
+    setResult((prev) => ({ ...prev, loading: true, error: void 0 }));
+    client.get(slug).then((snippet) => {
+      if (cancelled) return;
+      setResult({ snippet, loading: false });
+    }).catch((error) => {
+      if (cancelled) return;
+      setResult({ loading: false, error });
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [client, slug]);
+  return result;
+}
+
+// src/snippet-view.tsx
+import { useEffect as useEffect2, useMemo as useMemo2 } from "react";
+import DOMPurify from "dompurify";
+import { jsx as jsx2 } from "react/jsx-runtime";
+function SnippetView({
+  slug,
+  className,
+  loadingFallback = "Loading\u2026",
+  errorFallback = "Unable to load snippet",
+  onLoaded
+}) {
+  const state = useSnippet(slug);
+  const safeHtml = useMemo2(() => state.snippet ? DOMPurify.sanitize(state.snippet.html) : void 0, [state.snippet]);
+  useEffect2(() => {
+    onLoaded?.(state.snippet);
+  }, [state.snippet, onLoaded]);
+  if (state.loading) {
+    return /* @__PURE__ */ jsx2("div", { className, children: loadingFallback });
+  }
+  if (state.error) {
+    return /* @__PURE__ */ jsx2("div", { className, children: errorFallback });
+  }
+  if (!state.snippet) {
+    return /* @__PURE__ */ jsx2("div", { className, children: "Snippet not found" });
+  }
+  return /* @__PURE__ */ jsx2("div", { className, dangerouslySetInnerHTML: { __html: safeHtml ?? "" } });
+}
+export {
+  SnippetProvider,
+  SnippetView,
+  useSnippet,
+  useSnippetClient
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@mzebley/mark-down-react",
+  "version": "1.0.0",
+  "description": "mark↓ React 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.5"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}

package/src/context.tsx

@@ -0,0 +1,32 @@
+import { createContext, ReactNode, useContext, useMemo } from "react";
+import { SnippetClient, type SnippetClientOptions } from "@mzebley/mark-down";
+
+const SnippetClientContext = createContext<SnippetClient | null>(null);
+
+export interface SnippetProviderProps {
+  client?: SnippetClient;
+  options?: SnippetClientOptions;
+  children: ReactNode;
+}
+
+export function SnippetProvider({ client, options, children }: SnippetProviderProps) {
+  const value = useMemo(() => {
+    if (client) {
+      return client;
+    }
+    if (options) {
+      return new SnippetClient(options);
+    }
+    throw new Error("SnippetProvider requires either a client or options");
+  }, [client, options]);
+
+  return <SnippetClientContext.Provider value={value}>{children}</SnippetClientContext.Provider>;
+}
+
+export function useSnippetClient(): SnippetClient {
+  const client = useContext(SnippetClientContext);
+  if (!client) {
+    throw new Error("useSnippetClient must be used within a SnippetProvider");
+  }
+  return client;
+}

package/src/hooks.ts

@@ -0,0 +1,43 @@
+import { useEffect, useState } from "react";
+import type { Snippet } from "@mzebley/mark-down";
+import { useSnippetClient } from "./context";
+
+export interface UseSnippetResult {
+  snippet?: Snippet;
+  loading: boolean;
+  error?: Error;
+}
+
+export function useSnippet(slug?: string | null): UseSnippetResult {
+  const client = useSnippetClient();
+  const [result, setResult] = useState<UseSnippetResult>(() => ({
+    loading: Boolean(slug)
+  }));
+
+  useEffect(() => {
+    if (!slug) {
+      setResult({ loading: false });
+      return;
+    }
+
+    let cancelled = false;
+    setResult((prev) => ({ ...prev, loading: true, error: undefined }));
+
+    client
+      .get(slug)
+      .then((snippet) => {
+        if (cancelled) return;
+        setResult({ snippet, loading: false });
+      })
+      .catch((error: Error) => {
+        if (cancelled) return;
+        setResult({ loading: false, error });
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [client, slug]);
+
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./context";
+export * from "./hooks";
+export * from "./snippet-view";

package/src/snippet-view.tsx

@@ -0,0 +1,41 @@
+import { ReactNode, useEffect, useMemo } from "react";
+import DOMPurify from "dompurify";
+import type { Snippet } from "@mzebley/mark-down";
+import { useSnippet } from "./hooks";
+
+export interface SnippetViewProps {
+  slug: string;
+  className?: string;
+  loadingFallback?: ReactNode;
+  errorFallback?: ReactNode;
+  onLoaded?: (snippet?: Snippet) => void;
+}
+
+export function SnippetView({
+  slug,
+  className,
+  loadingFallback = "Loading…",
+  errorFallback = "Unable to load snippet",
+  onLoaded
+}: SnippetViewProps) {
+  const state = useSnippet(slug);
+  const safeHtml = useMemo(() => (state.snippet ? DOMPurify.sanitize(state.snippet.html) : undefined), [state.snippet]);
+
+  useEffect(() => {
+    onLoaded?.(state.snippet);
+  }, [state.snippet, onLoaded]);
+
+  if (state.loading) {
+    return <div className={className}>{loadingFallback}</div>;
+  }
+
+  if (state.error) {
+    return <div className={className}>{errorFallback}</div>;
+  }
+
+  if (!state.snippet) {
+    return <div className={className}>Snippet not found</div>;
+  }
+
+  return <div className={className} dangerouslySetInnerHTML={{ __html: safeHtml ?? "" }} />;
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}