Add documentation and stories; update React API (#1)

* Breaking: Flatten options into props for render blocks React
* Use TypeDoc to generate docs, tweak README.md
* Add usage documentation for VanillaJS and React
* Export createMakeCodeRenderBlocks (potentially breaking change)

Author: microbit-grace

.github/workflows/build-docs.yml

@@ -0,0 +1,39 @@
+name: build-docs
+on:
+  release:
+    types: [created]
+  push:
+    branches:
+      - '**'
+    tags:
+      - '**'
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - run: npm ci
+      - name: Build docs
+        run: npm run docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build
+
+  deploy:
+    if: ${{ startsWith(github.ref, 'refs/tags/') }}
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/build.yml

@@ -31,19 +31,3 @@ jobs:
         if: github.event_name == 'release' && github.event.action == 'created'
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-  deploy:
-    # https://github.com/actions/deploy-pages
-    runs-on: ubuntu-latest
-    permissions:
-      pages: write
-      id-token: write
-    needs: build
-    # Deploy to the github-pages environment
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    if: github.ref == 'refs/heads/main'
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

.gitignore

@@ -11,6 +11,7 @@ node_modules
 dist
 dist-ssr
 *.local
+docs/build
 
 # Editor directories and files
 .vscode/*

LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) YEAR AUTHOR
+Copyright (c) 2024-2025 Micro:bit Educational Foundation and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,21 +1,25 @@
-# React/JavaScript library for embedding Microsoft MakeCode as an iframe
+# MakeCode Embed
 
-This project is a work in progress.
+<a href="https://microbit-foundation.github.io/makecode-embed/" class="typedoc-ignore">This documentation is best viewed on the documentation site rather than GitHub or NPM package site.</a>
+
+This is a React/JavaScript library for embedding Microsoft MakeCode as an iframe.
 
 It is intended to be used by other Micro:bit Educational Foundation projects
 that need to embed MakeCode and, when the API stabilises, to be useful to others
 who embed MakeCode.
 
-## Documentation
+- [StoryBook demo of the components](https://makecode-embed.pages.dev/)
+
+## Usage
 
-There isn't any documentation yet. You can find a StoryBook demo of the
-components at https://microbit-foundation.github.io/makecode-embed/
+- [React usage documentation](docs/react.md)
+- [VanillaJS usage documentation](docs/vanilla.md)
 
 ## License
 
 This software is under the MIT open source license.
 
-[SPDX-License-Identifier: MIT](LICENSE)
+[SPDX-License-Identifier: MIT](LICENSE.md)
 
 We use dependencies via the NPM registry as specified by the package.json file under common Open Source licenses.
 

docs/custom.css

@@ -0,0 +1,4 @@
+/* Styling for hiding elements in the generated TypeDoc site. */
+a.typedoc-ignore {
+    display: none;
+}

docs/react.md

@@ -0,0 +1,48 @@
+---
+title: React Usage
+---
+
+# React Usage
+
+<a href="https://microbit-foundation.github.io/makecode-embed/" class="typedoc-ignore">This documentation is best viewed on the documentation site rather than GitHub or NPM package site.</a>
+
+## Blocks rendering
+
+Use {@link react.MakeCodeRenderBlocksProvider | MakeCodeRenderBlocksProvider} and {@link react.MakeCodeBlocksRendering | MakeCodeBlocksRendering} React components to render MakeCode blocks for a MakeCode project. Example MakeCode projects used for the demo are defined in [fixtures.ts](../src/stories/fixtures.ts).
+
+```js
+import {
+  MakeCodeRenderBlocksProvider,
+  MakeCodeBlocksRendering,
+} from '@microbit/makecode-embed/react';
+
+<MakeCodeRenderBlocksProvider>
+  <MakeCodeBlocksRendering code={project} />
+</MakeCodeRenderBlocksProvider>;
+```
+
+The provider manages a hidden, embedded MakeCode. If you have more than one code embed then place the provider at a suitable location. You can use the `disabled` prop to avoid loading MakeCode if you know it's not needed.
+
+For more examples, take a look at the [MakeCode blocks rendering demo source code](../src/stories/react/MakeCodeBlocksRendering.stories.tsx).
+
+## Embed MakeCode editor
+
+Use {@link react.MakeCodeFrame | MakeCodeFrame} component to embed MakeCode.
+
+```js
+import { MakeCodeFrame } from '@microbit/makecode-embed/react';
+
+<MakeCodeFrame
+  ref={ref}
+  controller={1}
+  controllerId="YOUR APP NAME HERE"
+  initialProjects={[savedProject]}
+  onEditorContentLoaded={(e) => console.log("MakeCode is now ready")},
+  onWorkspaceSave={(e) => {
+    // Set project as project changes in the editor.
+    setSavedProject(e.project);
+  }}
+/>;
+```
+
+For more examples, take a look at the [MakeCode frame demo source code](../src/stories/react/MakeCodeFrame.stories.tsx).

docs/vanilla.md

@@ -0,0 +1,70 @@
+---
+title: VanillaJS Usage
+---
+
+# VanillaJS Usage
+
+<a href="https://microbit-foundation.github.io/makecode-embed/" class="typedoc-ignore">This documentation is best viewed on the documentation site rather than GitHub or NPM package site.</a>
+
+## Blocks rendering
+
+Use {@link vanilla.createMakeCodeRenderBlocks | createMakeCodeRenderBlocks} to create a MakeCode block renderer. Initialise the renderer before calling `renderBlocks` with a {@link vanilla.RenderBlocksRequest | RenderBlocksRequest}, which includes a MakeCode project ([see examples](../src/stories/fixtures.ts)). The function will return a {@link vanilla.RenderBlocksResponse | RenderBlocksResponse}.
+
+```js
+import { createMakeCodeRenderBlocks } from "@microbit/makecode-embed/vanilla";
+
+const renderer = createMakeCodeRenderBlocks({});
+renderer.initialize();
+const result = await renderer.renderBlocks({ code: makeCodeProject });
+
+document.querySelector<HTMLDivElement>("#app")!.innerHTML = `
+  <div>
+    ${result.svg}
+  </div>
+`;
+```
+
+For more examples, take a look at the [MakeCode blocks rendering demo source code](../src/stories/vanilla/makecode-render-blocks.stories.tsx).
+
+## Embed MakeCode editor
+
+Use {@link vanilla.MakeCodeFrameDriver | MakeCodeFrameDriver} class to create a driverRef for an iframe element. The iframe element src URL can be generated using {@link vanilla.createMakeCodeURL | createMakeCodeURL}.
+
+```js
+import {
+  Project,
+  MakeCodeFrameDriver,
+  createMakeCodeURL,
+} from "@microbit/makecode-embed/vanilla";
+
+// Set up an iframe element.
+const iframe = document.createElement("iframe");
+iframe.allow = "usb; autoplay; camera; microphone;";
+iframe.src = createMakeCodeURL(
+  "https://makecode.microbit.org",
+  undefined, // Version.
+  undefined, // Language.
+  1, // Controller.
+  undefined // Query params.
+);
+iframe.width = "100%";
+iframe.height = "100%";
+
+document.querySelector<HTMLDivElement>("#app")!.appendChild(iframe);
+
+// Create and initialise an instance of MakeCodeFrameDriver.
+const driverRef = new MakeCodeFrameDriver(
+  {
+    controllerId: "YOUR APP NAME HERE",
+    initialProjects: async () => [makeCodeProject],
+    onEditorContentLoaded: (e) => console.log("MakeCode is now ready"),
+    onWorkspaceSave: (e) => {
+      console.log(e.project!.header!.id, e.project);
+    },
+  },
+  () => iframe
+);
+driverRef.initialize();
+```
+
+For more examples, take a look at the [MakeCode frame demo source code](../src/stories/vanilla/makecode-frame-driver.stories.tsx).