feat: Create structure for guided tutorial of the language

.gitignore

@@ -10,6 +10,7 @@ node_modules/
 .next/
 out/
 apps/docs/out/
+apps/guide/out/
 index_data/*.json
 apps/docs/index_data/*.json
 
@@ -25,12 +26,15 @@ apps/docs/temp-jsx-preserve
 .merlin
 lib/
 apps/docs/lib/
+apps/guide/lib/
 packages/*/lib/
 
 .vercel
 
 apps/docs/src/**/*.mjs
 apps/docs/src/**/*.jsx
+apps/guide/src/**/*.mjs
+apps/guide/src/**/*.jsx
 packages/*/src/**/*.mjs
 packages/*/src/**/*.jsx
 apps/docs/scripts/gendocs.mjs
@@ -52,17 +56,26 @@ dist
 build
 apps/docs/dist
 apps/docs/build
+apps/guide/dist
+apps/guide/build
 .react-router
 apps/docs/.react-router
+apps/guide/.react-router
 mdx-manifest.json
 apps/docs/mdx-manifest.json
 
 apps/docs/app/**/*.mjs
 apps/docs/app/**/*.jsx
+apps/guide/app/**/*.mjs
+apps/guide/app/**/*.jsx
+!apps/guide/app/root.jsx
+!apps/guide/app/routes.jsx
 apps/docs/functions/**/*.mjs
 apps/docs/functions/**/*.jsx
 apps/docs/__tests__/**/*.mjs
 apps/docs/__tests__/**/*.jsx
+apps/guide/__tests__/**/*.mjs
+apps/guide/__tests__/**/*.jsx
 apps/docs/e2e/**/*.mjs
 apps/docs/e2e/**/*.jsx
 !_shims.mjs
@@ -95,3 +108,4 @@ apps/docs/.env.local
 !apps/docs/__tests__/__screenshots__/**/*
 .vitest-attachments
 apps/docs/.vitest-attachments
+apps/guide/.vitest-attachments

apps/docs/app/root.js

@@ -0,0 +1 @@
+export { default } from "./DocsRoot.jsx";

apps/docs/app/routes.js

@@ -0,0 +1 @@
+export { default } from "./DocsRoutes.jsx";

apps/docs/package.json

@@ -6,7 +6,7 @@
   "author": "Patrick Ecker <ryyppy@users.noreply.github.com>",
   "type": "module",
   "scripts": {
-    "build:scripts": "yarn dlx tsdown@0.21.7 scripts/*.jsx -d _scripts --no-clean --ext .mjs",
+    "build:scripts": "cd ../.. && yarn dlx tsdown@0.21.7 apps/docs/scripts/*.jsx -d apps/docs/_scripts --no-clean --ext .mjs",
     "build:generate-llms": "node _scripts/generate_llms.mjs",
     "build:generate-sitemap": "node _scripts/generate_sitemap.mjs build/client out",
     "build:res": "rescript build --warn-error +3+8+11+12+26+27+31+32+33+34+35+39+44+45+110",

apps/docs/react-router.config.mjs

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 
-const { stdlibPaths } = await import("./app/routes.jsx");
+const { stdlibPaths } = await import("./app/DocsRoutes.jsx");
 
 export default {
   ssr: false,

apps/docs/src/components/Search.res

@@ -68,9 +68,9 @@ let normalizeHitUrls = (items: array<DocSearch.docSearchHit>, ~siteUrl: string)
     {...hit, url, url_without_anchor, hierarchy}
   })
 
-let navigator = (~siteUrl: string): DocSearch.navigator => {
+let navigator = (~siteUrl: string, ~navigate: ReactRouter.navigate): DocSearch.navigator => {
   navigate: ({itemUrl}) => {
-    ReactRouter.navigate(toRelativeSiteUrl(itemUrl, ~siteUrl))
+    navigate(toRelativeSiteUrl(itemUrl, ~siteUrl))
   },
 }
 
@@ -301,6 +301,44 @@ module ErrorBoundary = {
   }
 }
 
+module ActiveDocSearch = {
+  @react.component
+  let make = (
+    ~apiKey,
+    ~appId,
+    ~indexName,
+    ~deactivateSearch: unit => unit,
+    ~onClose: unit => unit,
+  ) => {
+    let navigate = ReactRouter.useNavigate()
+
+    switch ReactDOM.querySelector("body") {
+    | Some(element) =>
+      ReactDOM.createPortal(
+        <ErrorBoundary onClose=deactivateSearch>
+          <DocSearch
+            apiKey
+            appId
+            indexName
+            navigator={navigator(~siteUrl=Env.root_url, ~navigate)}
+            transformItems={items => normalizeHitUrls(items, ~siteUrl=Env.root_url)}
+            hitComponent
+            onClose
+            initialScrollY={window.scrollY->Float.toInt}
+            searchParameters={
+              distinct: 3,
+              hitsPerPage: 20,
+              attributesToSnippet: ["content:9999"],
+            }
+          />
+        </ErrorBoundary>,
+        element,
+      )
+    | None => React.null
+    }
+  }
+}
+
 @react.component
 let make = () => {
   let (state, setState) = React.useState(_ => Inactive)
@@ -392,31 +430,7 @@ let make = () => {
         <Icon.MagnifierGlass className="fill-current" />
       </button>
       {switch state {
-      | Active =>
-        switch ReactDOM.querySelector("body") {
-        | Some(element) =>
-          ReactDOM.createPortal(
-            <ErrorBoundary onClose=deactivateSearch>
-              <DocSearch
-                apiKey=searchApiKey
-                appId
-                indexName
-                navigator={navigator(~siteUrl=Env.root_url)}
-                transformItems={items => normalizeHitUrls(items, ~siteUrl=Env.root_url)}
-                hitComponent
-                onClose
-                initialScrollY={window.scrollY->Float.toInt}
-                searchParameters={
-                  distinct: 3,
-                  hitsPerPage: 20,
-                  attributesToSnippet: ["content:9999"],
-                }
-              />
-            </ErrorBoundary>,
-            element,
-          )
-        | None => React.null
-        }
+      | Active => <ActiveDocSearch apiKey=searchApiKey appId indexName deactivateSearch onClose />
       | Inactive => React.null
       }}
     </>

apps/guide/__tests__/GuideCompilerFeedback_.test.res

@@ -0,0 +1,83 @@
+open Vitest
+
+test("maps compiler diagnostics into editor errors", async () => {
+  let locMsg: RescriptCompilerApi.LocMsg.t = {
+    fullMsg: "Full compiler error",
+    shortMsg: "Expected a string",
+    row: 2,
+    column: 7,
+    endRow: 2,
+    endColumn: 12,
+  }
+
+  let editorError = GuideCompilerFeedback.locMsgToEditorError(~kind=#Error, locMsg)
+
+  expect(editorError.row)->toBe(2)
+  expect(editorError.column)->toBe(7)
+  expect(editorError.endRow)->toBe(2)
+  expect(editorError.endColumn)->toBe(12)
+  expect(editorError.text)->toBe("Expected a string")
+
+  let outputLine =
+    GuideCompilerFeedback.compileFailToOutputLines(TypecheckErr([locMsg]))
+    ->Array.get(0)
+    ->Option.getOrThrow
+  expect(outputLine)->toBe("[E] Line 2, 7: Expected a string")
+})
+
+test("maps compiler type hints into hover hints", async () => {
+  let typeHint = RescriptCompilerApi.TypeHint.Binding({
+    start: {line: 1, col: 4},
+    end: {line: 1, col: 12},
+    hint: "string",
+  })
+
+  let hoverHint =
+    GuideCompilerFeedback.typeHintsToHoverHints([typeHint])->Array.get(0)->Option.getOrThrow
+
+  expect(hoverHint.start.line)->toBe(1)
+  expect(hoverHint.start.col)->toBe(4)
+  expect(hoverHint.end.line)->toBe(1)
+  expect(hoverHint.end.col)->toBe(12)
+  expect(hoverHint.hint)->toBe("string")
+})
+
+test("keeps the previous output while a successful compile waits for runtime logs", async () => {
+  let typeHint = RescriptCompilerApi.TypeHint.Binding({
+    start: {line: 1, col: 4},
+    end: {line: 1, col: 12},
+    hint: "string",
+  })
+
+  let outputUpdate = GuideCompilerFeedback.compilationResultToOutputUpdate(
+    Success({
+      jsCode: "let value = 52;",
+      warnings: [],
+      typeHints: [typeHint],
+      time: 1.0,
+    }),
+  )
+
+  expect(outputUpdate->Option.isNone)->toBe(true)
+})
+
+test("shows compiler errors as output updates", async () => {
+  let locMsg: RescriptCompilerApi.LocMsg.t = {
+    fullMsg: "Full compiler error",
+    shortMsg: "Expected a string",
+    row: 2,
+    column: 7,
+    endRow: 2,
+    endColumn: 12,
+  }
+
+  let output =
+    GuideCompilerFeedback.compilationResultToOutputUpdate(
+      Fail(TypecheckErr([locMsg])),
+    )->Option.getOrThrow
+
+  expect(output.status)->toBe("Compiler error")
+  expect(output.diagnostics->Array.get(0)->Option.getOrThrow)->toBe(
+    "[E] Line 2, 7: Expected a string",
+  )
+})

apps/guide/__tests__/GuideCompilerSettings_.test.res

@@ -0,0 +1,18 @@
+open Vitest
+
+test("selects the latest stable ReScript compiler with ESM output", async () => {
+  let version =
+    GuideCompilerSettings.latestStableVersion([
+      "v12.1.0-alpha.1",
+      "v11.1.4",
+      "v12.0.0",
+      "v12.2.0-beta.1",
+      "v12.1.3",
+    ])
+    ->Option.getOrThrow
+    ->Semver.toString
+
+  expect(version)->toBe("v12.1.3")
+  expect(GuideCompilerSettings.moduleSystem)->toBe("esmodule")
+  expect(GuideCompilerSettings.warnFlags->String.includes("-109"))->toBe(true)
+})