@markgrafhq/docusaurus-plugin-markgraf 0.0.42

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Eibes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @markgrafhq/docusaurus-plugin-markgraf
+
+Docusaurus plugin + component for embedding [markgraf](https://github.com/markgrafhq) animations.
+
+## Install
+
+```bash
+npm install @markgrafhq/docusaurus-plugin-markgraf @markgrafhq/markgraf-react
+```
+
+## Configure
+
+```js
+// docusaurus.config.js
+import remarkMarkgraf from "@markgrafhq/docusaurus-plugin-markgraf/remark";
+
+export default {
+  presets: [
+    [
+      "classic",
+      {
+        docs: { remarkPlugins: [remarkMarkgraf] },
+        blog: { remarkPlugins: [remarkMarkgraf] },
+      },
+    ],
+  ],
+  plugins: ["@markgrafhq/docusaurus-plugin-markgraf"],
+};
+```
+
+Then add the CSS in your custom CSS entry:
+
+```css
+@import "@markgrafhq/docusaurus-plugin-markgraf/css";
+```
+
+## Use
+
+Fenced code blocks with the `markgraf` language render as live players:
+
+````markdown
+```markgraf
+seed 1
+scene v1 {
+  + client: Client
+  + api: API
+  + client -> api
+  client ~> api: GET /user/42
+}
+```
+````
+
+Or use the component directly in MDX:
+
+```mdx
+import { Markgraf } from "@markgrafhq/docusaurus-plugin-markgraf";
+
+<Markgraf src={`seed 1\nscene v1 { + a: A }`} />
+```
+
+Players include the floating play, scrub, time, and speed controls by default.
+Hide them with `controls={false}`, or replace them with a render function that
+receives the underlying `MarkgrafApi`:
+
+```mdx
+<Markgraf
+  src={source}
+  controls={(api) => <MyDiagramControls api={api} />}
+/>
+```

package/dist/Markgraf.d.ts

@@ -0,0 +1,16 @@
+import React, { type ReactNode } from "react";
+import { type MarkgrafApi } from "@markgrafhq/markgraf-react";
+type Renderer = "canvas" | "svg";
+export type MarkgrafControls = boolean | ((api: MarkgrafApi<Element>) => ReactNode);
+export interface MarkgrafProps {
+    src: string;
+    renderer?: Renderer;
+    className?: string;
+    /**
+     * Shows the transport bar by default. Pass `false` to hide it, or a render
+     * function to replace it with controls driven by the same player API.
+     */
+    controls?: MarkgrafControls;
+}
+export default function Markgraf(props: MarkgrafProps): React.JSX.Element;
+export {};

package/dist/Markgraf.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { useMarkgraf } from "@markgrafhq/markgraf-react";
+const playIcon = (_jsx("svg", { viewBox: "0 0 15 15", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M3.24 2.05a.5.5 0 0 1 .52.02l8.5 5a.5.5 0 0 1 0 .86l-8.5 5A.5.5 0 0 1 3 12.5v-10a.5.5 0 0 1 .24-.45Z" }) }));
+const pauseIcon = (_jsx("svg", { viewBox: "0 0 15 15", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M3.5 2.5a.5.5 0 0 1 .5-.5h2a.5.5 0 0 1 .5.5v10a.5.5 0 0 1-.5.5H4a.5.5 0 0 1-.5-.5v-10Zm5 0A.5.5 0 0 1 9 2h2a.5.5 0 0 1 .5.5v10a.5.5 0 0 1-.5.5H9a.5.5 0 0 1-.5-.5v-10Z" }) }));
+const speedIcon = (_jsx("svg", { className: "markgraf-doc-speed-icon", viewBox: "0 0 15 15", "aria-hidden": "true", focusable: "false", children: _jsx("path", { d: "M3.14 5.64a.5.5 0 0 1 .71 0L7.5 9.29l3.65-3.65a.5.5 0 0 1 .7.71l-4 4a.5.5 0 0 1-.7 0l-4-4a.5.5 0 0 1 0-.71Z" }) }));
+const useDocumentTheme = () => {
+    const [theme, setTheme] = useState("light");
+    useEffect(() => {
+        const root = document.documentElement;
+        const update = () => setTheme(root.dataset.theme === "dark" ? "dark" : "light");
+        update();
+        const observer = new MutationObserver(update);
+        observer.observe(root, {
+            attributes: true,
+            attributeFilter: ["data-theme"],
+        });
+        return () => observer.disconnect();
+    }, []);
+    return theme;
+};
+const formatTime = (seconds) => {
+    const safe = Number.isFinite(seconds) ? Math.max(0, seconds) : 0;
+    const minutes = Math.floor(safe / 60);
+    const remainder = safe - minutes * 60;
+    return `${minutes}:${remainder.toFixed(1).padStart(4, "0")}`;
+};
+const DefaultControls = ({ api, speed, setSpeed, }) => {
+    const duration = Number.isFinite(api.duration)
+        ? Math.max(0, api.duration)
+        : 0;
+    const time = Number.isFinite(api.time)
+        ? Math.max(0, Math.min(api.time, duration))
+        : 0;
+    return (_jsxs("div", { className: "markgraf-doc-controls", "aria-label": "Diagram playback controls", children: [_jsx("button", { className: "markgraf-doc-play", type: "button", "aria-label": api.playing ? "Pause diagram" : "Play diagram", "aria-pressed": api.playing, disabled: !api.ready, onClick: api.toggle, children: api.playing ? pauseIcon : playIcon }), _jsx("input", { className: "markgraf-doc-scrub", type: "range", "aria-label": "Diagram time", min: "0", max: Math.max(duration, 0.001), step: "0.01", value: time, disabled: !api.ready, onChange: (event) => api.seek(event.currentTarget.valueAsNumber) }), _jsxs("output", { className: "markgraf-doc-time", "aria-live": "off", children: [formatTime(time), " / ", formatTime(duration)] }), _jsxs("div", { className: "markgraf-doc-speed-control", children: [_jsxs("select", { className: "markgraf-doc-speed", "aria-label": "Playback speed", value: speed, disabled: !api.ready, onChange: (event) => setSpeed(Number(event.currentTarget.value)), children: [_jsx("option", { value: "0.5", children: "0.5\u00D7" }), _jsx("option", { value: "1", children: "1\u00D7" }), _jsx("option", { value: "1.5", children: "1.5\u00D7" }), _jsx("option", { value: "2", children: "2\u00D7" })] }), speedIcon] })] }));
+};
+const Controls = ({ api, controls, }) => {
+    const [speed, setSpeed] = useState(1);
+    useEffect(() => {
+        if (controls === true && api.ready)
+            api.setSpeed(speed);
+    }, [api.ready, controls, speed]);
+    if (typeof controls === "function")
+        return controls(api);
+    if (!controls)
+        return null;
+    return _jsx(DefaultControls, { api: api, speed: speed, setSpeed: setSpeed });
+};
+const CanvasPlayer = ({ src, theme, className, controls, }) => {
+    const api = useMarkgraf(src, { renderer: "canvas", theme });
+    return (_jsxs("div", { className: `markgraf-doc-player ${className ?? ""}`, "data-markgraf-theme": theme, children: [_jsx("canvas", { className: "markgraf-player markgraf-doc-stage", ref: api.elementRef, onClick: api.toggle, "aria-label": "Animated Markgraf diagram" }), _jsx(Controls, { api: api, controls: controls })] }));
+};
+const SvgPlayer = ({ src, theme, className, controls, }) => {
+    const api = useMarkgraf(src, { renderer: "svg", theme });
+    return (_jsxs("div", { className: `markgraf-doc-player ${className ?? ""}`, "data-markgraf-theme": theme, children: [_jsx("svg", { className: "markgraf-player markgraf-doc-stage", ref: api.elementRef, onClick: api.toggle, "aria-label": "Animated Markgraf diagram" }), _jsx(Controls, { api: api, controls: controls })] }));
+};
+const MountedPlayer = (props) => {
+    const theme = useDocumentTheme();
+    return props.renderer === "svg" ? (_jsx(SvgPlayer, { ...props, renderer: "svg", theme: theme, controls: props.controls ?? true })) : (_jsx(CanvasPlayer, { ...props, renderer: "canvas", theme: theme, controls: props.controls ?? true }));
+};
+export default function Markgraf(props) {
+    const [mounted, setMounted] = useState(false);
+    useEffect(() => setMounted(true), []);
+    if (!mounted) {
+        return (_jsx("div", { className: `markgraf-doc-player ${props.className ?? ""}`, "data-markgraf-placeholder": "" }));
+    }
+    return _jsx(MountedPlayer, { ...props });
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import remarkMarkgraf from "./remark-markgraf.mjs";
+export { default as Markgraf, type MarkgrafControls, type MarkgrafProps, } from "./Markgraf.js";
+export default function pluginMarkgraf(): {
+    name: string;
+    configureWebpack(): {
+        resolve: {
+            extensionAlias: {
+                ".js": string[];
+            };
+        };
+    };
+};
+export { remarkMarkgraf };

package/dist/index.js

@@ -0,0 +1,11 @@
+import remarkMarkgraf from "./remark-markgraf.mjs";
+export { default as Markgraf, } from "./Markgraf.js";
+export default function pluginMarkgraf() {
+    return {
+        name: "markgraf-docusaurus",
+        configureWebpack() {
+            return { resolve: { extensionAlias: { ".js": [".js", ".ts", ".tsx"] } } };
+        },
+    };
+}
+export { remarkMarkgraf };

package/dist/markgraf-react.css

@@ -0,0 +1,154 @@
+@import "@markgrafhq/markgraf-react/css";
+
+.markgraf-doc-player {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  min-width: 0;
+  min-height: 11.25rem;
+  aspect-ratio: 16 / 9;
+  overflow: hidden;
+  border: 1px solid color-mix(in srgb, currentColor 14%, transparent);
+  border-radius: 0.875rem;
+  background: #ffffff;
+  box-shadow: 0 1rem 3rem rgb(0 0 0 / 10%);
+}
+
+.markgraf-doc-player[data-markgraf-theme="dark"] {
+  background: #101827;
+}
+
+.markgraf-doc-stage {
+  display: block;
+  width: 100%;
+  height: 100%;
+  min-height: 11.25rem;
+  cursor: pointer;
+}
+
+.markgraf-doc-controls {
+  position: absolute;
+  z-index: 2;
+  right: 50%;
+  bottom: 0.75rem;
+  display: grid;
+  grid-template-columns: 1.75rem minmax(7rem, 1fr) auto auto;
+  align-items: center;
+  gap: 0.5rem;
+  width: min(35rem, calc(100% - 2rem));
+  padding: 0.375rem 0.5rem;
+  border: 1px solid rgb(255 255 255 / 14%);
+  border-radius: 999px;
+  color: #ffffff;
+  background: rgb(8 13 22 / 58%);
+  box-shadow: 0 0.875rem 2.75rem rgb(0 0 0 / 28%);
+  opacity: 0.78;
+  transform: translateX(50%);
+  transition:
+    opacity 140ms ease,
+    background 140ms ease;
+  backdrop-filter: blur(18px);
+}
+
+.markgraf-doc-player:hover .markgraf-doc-controls,
+.markgraf-doc-controls:focus-within {
+  background: rgb(8 13 22 / 78%);
+  opacity: 0.98;
+}
+
+.markgraf-doc-play {
+  display: grid;
+  width: 1.75rem;
+  height: 1.75rem;
+  padding: 0;
+  border: 0;
+  border-radius: 999px;
+  place-items: center;
+  color: inherit;
+  background: rgb(255 255 255 / 10%);
+  cursor: pointer;
+}
+
+.markgraf-doc-play:hover,
+.markgraf-doc-play:focus-visible {
+  background: rgb(255 255 255 / 20%);
+}
+
+.markgraf-doc-play svg {
+  width: 0.875rem;
+  height: 0.875rem;
+}
+
+.markgraf-doc-scrub {
+  min-width: 0;
+  height: 0.875rem;
+  margin: 0;
+  accent-color: #ffffff;
+  cursor: pointer;
+}
+
+.markgraf-doc-time {
+  color: rgb(255 255 255 / 76%);
+  font-family: var(
+    --sl-font-mono,
+    var(--ifm-font-family-monospace, ui-monospace, monospace)
+  );
+  font-size: 0.625rem;
+  line-height: 1;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.markgraf-doc-speed-control {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.markgraf-doc-speed {
+  appearance: none;
+  width: 100%;
+  padding: 0.1875rem 1.375rem 0.1875rem 0.5rem;
+  border: 0;
+  border-radius: 999px;
+  color: #ffffff;
+  background: rgb(255 255 255 / 10%);
+  font-size: 0.625rem;
+  cursor: pointer;
+}
+
+.markgraf-doc-speed-icon {
+  position: absolute;
+  right: 0.4375rem;
+  width: 0.75rem;
+  height: 0.75rem;
+  color: rgb(255 255 255 / 72%);
+  pointer-events: none;
+}
+
+.markgraf-doc-speed option {
+  color: #111827;
+  background: #ffffff;
+}
+
+.markgraf-doc-controls :disabled {
+  cursor: wait;
+  opacity: 0.5;
+}
+
+@media (max-width: 32rem) {
+  .markgraf-doc-controls {
+    grid-template-columns: 1.75rem minmax(5rem, 1fr) auto;
+  }
+
+  .markgraf-doc-time {
+    display: none;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .markgraf-doc-controls {
+    transition: none;
+  }
+}

package/dist/remark-markgraf.js

@@ -0,0 +1,56 @@
+import { visit } from "unist-util-visit";
+
+const importNode = {
+  type: "mdxjsEsm",
+  value: 'import Markgraf from "@markgrafhq/docusaurus-plugin-markgraf/dist/Markgraf.js";',
+  data: {
+    estree: {
+      type: "Program",
+      sourceType: "module",
+      body: [
+        {
+          type: "ImportDeclaration",
+          specifiers: [
+            {
+              type: "ImportDefaultSpecifier",
+              local: { type: "Identifier", name: "Markgraf" },
+            },
+          ],
+          source: {
+            type: "Literal",
+            value: "@markgrafhq/docusaurus-plugin-markgraf/dist/Markgraf.js",
+            raw: '"@markgrafhq/docusaurus-plugin-markgraf/dist/Markgraf.js"',
+          },
+        },
+      ],
+    },
+  },
+};
+
+export default function remarkMarkgraf() {
+  return (tree) => {
+    let needsImport = false;
+
+    visit(tree, "code", (node, index, parent) => {
+      if (node.lang !== "markgraf" || !parent || index == null) return;
+
+      needsImport = true;
+
+      const src = node.value;
+      parent.children[index] = {
+        type: "mdxJsxFlowElement",
+        name: "Markgraf",
+        attributes: [
+          {
+            type: "mdxJsxAttribute",
+            name: "src",
+            value: src,
+          },
+        ],
+        children: [],
+      };
+    });
+
+    if (needsImport) tree.children.unshift(importNode);
+  };
+}

package/dist/remark-markgraf.mjs

@@ -0,0 +1,56 @@
+import { visit } from "unist-util-visit";
+
+const importNode = {
+  type: "mdxjsEsm",
+  value: 'import Markgraf from "@markgrafhq/docusaurus-plugin-markgraf/dist/Markgraf.js";',
+  data: {
+    estree: {
+      type: "Program",
+      sourceType: "module",
+      body: [
+        {
+          type: "ImportDeclaration",
+          specifiers: [
+            {
+              type: "ImportDefaultSpecifier",
+              local: { type: "Identifier", name: "Markgraf" },
+            },
+          ],
+          source: {
+            type: "Literal",
+            value: "@markgrafhq/docusaurus-plugin-markgraf/dist/Markgraf.js",
+            raw: '"@markgrafhq/docusaurus-plugin-markgraf/dist/Markgraf.js"',
+          },
+        },
+      ],
+    },
+  },
+};
+
+export default function remarkMarkgraf() {
+  return (tree) => {
+    let needsImport = false;
+
+    visit(tree, "code", (node, index, parent) => {
+      if (node.lang !== "markgraf" || !parent || index == null) return;
+
+      needsImport = true;
+
+      const src = node.value;
+      parent.children[index] = {
+        type: "mdxJsxFlowElement",
+        name: "Markgraf",
+        attributes: [
+          {
+            type: "mdxJsxAttribute",
+            name: "src",
+            value: src,
+          },
+        ],
+        children: [],
+      };
+    });
+
+    if (needsImport) tree.children.unshift(importNode);
+  };
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@markgrafhq/docusaurus-plugin-markgraf",
+  "version": "0.0.42",
+  "description": "Docusaurus plugin + component for embedding markgraf animations. Transforms ```markgraf fenced code blocks into a live player and exposes a <Markgraf src=\"…\" /> MDX component.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./remark": {
+      "default": "./dist/remark-markgraf.js"
+    },
+    "./dist/*": "./dist/*",
+    "./css": "./dist/markgraf-react.css"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./dist/markgraf-react.css"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && cp src/remark-markgraf.mjs dist/remark-markgraf.mjs && cp src/remark-markgraf.mjs dist/remark-markgraf.js && cp src/player.css dist/markgraf-react.css"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": ">=3",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@markgrafhq/markgraf-react": "0.0.42",
+    "unist-util-visit": "^5"
+  },
+  "devDependencies": {
+    "@types/react": "^18",
+    "typescript": "^5"
+  },
+  "keywords": [
+    "markgraf",
+    "docusaurus",
+    "docusaurus-plugin",
+    "mdx",
+    "remark",
+    "animation",
+    "diagram"
+  ],
+  "license": "MIT",
+  "author": "Mark Eibes <mark.eibes@gmail.com>",
+  "homepage": "https://github.com/markgrafhq/docusaurus-plugin-markgraf#readme",
+  "bugs": "https://github.com/markgrafhq/docusaurus-plugin-markgraf/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markgrafhq/docusaurus-plugin-markgraf.git"
+  }
+}