Merge branch 'master' of github.com:rescript-lang/rescript-lang.org into vlk/split-out-api-overview

Author: jderochervlk

app/routes.res

@@ -11,6 +11,17 @@ let stdlibPaths = {
   ->Array.filter(path => path !== "docs/manual/api/stdlib")
 }
 
+let domPaths = {
+  let rawFile = await Node.Fs.readFile("./markdown-pages/docs/api/dom.json", "utf-8")
+  let json = JSON.parseOrThrow(rawFile)
+  switch json {
+  | Object(json) => Dict.keysToArray(json)
+  | _ => []
+  }
+  ->Array.map(key => "docs/manual/api/" ++ key)
+  ->Array.filter(path => path !== "docs/manual/api/dom")
+}
+
 let beltPaths = {
   let rawFile = await Node.Fs.readFile("./markdown-pages/docs/api/belt.json", "utf-8")
   let json = JSON.parseOrThrow(rawFile)
@@ -25,6 +36,9 @@ let beltPaths = {
 let stdlibRoutes =
   stdlibPaths->Array.map(path => route(path, "./routes/ApiRoute.jsx", ~options={id: path}))
 
+let domRoutes =
+  domPaths->Array.map(path => route(path, "./routes/ApiRoute.jsx", ~options={id: path}))
+
 let beltRoutes =
   beltPaths->Array.map(path => route(path, "./routes/ApiRoute.jsx", ~options={id: path}))
 
@@ -46,7 +60,9 @@ let mdxRoutes = mdxRoutes("./routes/MdxRoute.jsx")->Array.filter(r =>
       String.startsWith(path, "blog/") ||
       path === "community" ||
       String.startsWith(path, "community/") ||
-      path === "docs/manual/api"
+      path === "docs/manual/api" ||
+      path === "community" ||
+      String.startsWith(path, "community/")
     )
     ->Option.getOr(false)
   )
@@ -67,6 +83,7 @@ let default = [
   route("docs/manual/api/dom", "./routes/ApiRoute.jsx", ~options={id: "api-dom"}),
   ...stdlibRoutes,
   ...beltRoutes,
+  ...domRoutes,
   ...blogArticleRoutes,
   ...communityRoutes,
   ...mdxRoutes,

app/routes/DocsGuidelinesRoute.res

@@ -0,0 +1,88 @@
+type loaderData = {
+  compiledMdx: CompiledMdx.t,
+  entries: array<TableOfContents.entry>,
+  title: string,
+  description: string,
+  filePath: string,
+}
+
+let loader: ReactRouter.Loader.t<loaderData> = async ({request}) => {
+  let {pathname} = WebAPI.URL.make(~url=request.url)
+  let filePath = MdxFile.resolveFilePath(
+    (pathname :> string),
+    ~dir="markdown-pages/docs/guidelines",
+    ~alias="docs/guidelines",
+  )
+
+  let raw = await Node.Fs.readFile(filePath, "utf-8")
+  let {frontmatter}: MarkdownParser.result = MarkdownParser.parseSync(raw)
+
+  let description = switch frontmatter {
+  | Object(dict) =>
+    switch dict->Dict.get("description") {
+    | Some(String(s)) => s
+    | _ => ""
+    }
+  | _ => ""
+  }
+
+  let title = switch frontmatter {
+  | Object(dict) =>
+    switch dict->Dict.get("title") {
+    | Some(String(s)) => s
+    | _ => ""
+    }
+  | _ => ""
+  }
+
+  let compiledMdx = await MdxFile.compileMdx(raw, ~filePath, ~remarkPlugins=Mdx.plugins)
+
+  // Build table of contents entries from markdown headings
+  let markdownTree = Mdast.fromMarkdown(raw)
+  let tocResult = Mdast.toc(markdownTree, {maxDepth: 2})
+
+  let headers = Dict.make()
+  Mdast.reduceHeaders(tocResult.map, headers)
+
+  let entries =
+    headers
+    ->Dict.toArray
+    ->Array.map(((header, url)): TableOfContents.entry => {
+      header,
+      href: (url :> string),
+    })
+    ->Array.slice(~start=2) // skip document entry and H1 title, keep h2 sections
+
+  {
+    compiledMdx,
+    entries,
+    title: `${title} | ReScript Guidelines`,
+    description,
+    filePath,
+  }
+}
+
+let default = () => {
+  let {compiledMdx, entries, title, description, filePath} = ReactRouter.useLoaderData()
+
+  let editHref = `https://github.com/rescript-lang/rescript-lang.org/blob/master/${filePath}`
+
+  let categories: array<SidebarLayout.Sidebar.Category.t> = []
+
+  <>
+    <Meta title description />
+    <NavbarSecondary />
+    <NavbarTertiary>
+      <a
+        href=editHref className="inline text-14 hover:underline text-fire" rel="noopener noreferrer"
+      >
+        {React.string("Edit")}
+      </a>
+    </NavbarTertiary>
+    <DocsLayout categories activeToc={title, entries}>
+      <div className="markdown-body">
+        <MdxContent compiledMdx />
+      </div>
+    </DocsLayout>
+  </>
+}

app/routes/DocsGuidelinesRoute.resi

@@ -0,0 +1,11 @@
+type loaderData = {
+  compiledMdx: CompiledMdx.t,
+  entries: array<TableOfContents.entry>,
+  title: string,
+  description: string,
+  filePath: string,
+}
+
+let loader: ReactRouter.Loader.t<loaderData>
+
+let default: unit => React.element

data/api/v13.0.0/stdlib.json

@@ -2427,9 +2427,9 @@
         "kind": "value",
         "name": "compare",
         "docstrings": [
-          "`compare(collator, a, b)` compares two strings using the rules of `collator`. Returns a negative number when `a` comes before `b`, `0` when equal, and a positive number otherwise.\n\n## Examples\n\n```rescript\nlet collator = Intl.Collator.make(~locales=[\"en-US\"])\ncollator->Intl.Collator.compare(\"apple\", \"banana\") < 0\n```"
+          "`compare(collator, a, b)` compares two strings using the rules of `collator`. Returns a negative number when `a` comes before `b`, `0` when equal, and a positive number otherwise.\n\n## Examples\n\n```rescript\nlet collator = Intl.Collator.make(~locales=[\"en-US\"])\nOrdering.isLess(collator->Intl.Collator.compare(\"apple\", \"banana\"))\n```"
         ],
-        "signature": "let compare: (t, string, string) => int"
+        "signature": "let compare: (t, string, string) => Ordering.t"
       },
       {
         "id": "Stdlib.Intl.Collator.ignore",
@@ -5984,9 +5984,9 @@
         "kind": "value",
         "name": "localeCompare",
         "docstrings": [
-          "`localeCompare(referenceStr, compareStr)` returns a float than indicatings\nwhether a reference string comes before or after, or is the same as the given\nstring in sort order. If `referenceStr` occurs before `compareStr` positive if\nthe `referenceStr` occurs after `compareStr`, `0` if they are equivalent.\nDo not rely on exact return values of `-1` or `1`\nSee [`String.localeCompare`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare) on MDN.\n\n## Examples\n\n```rescript\nString.localeCompare(\"a\", \"c\") < 0.0 == true\nString.localeCompare(\"a\", \"a\") == 0.0\n```"
+          "`localeCompare(referenceStr, compareStr, ~locales=?, ~options=?)` returns a float indicating\nwhether a reference string comes before or after, or is the same as the given\nstring in sort order. Returns a negative value if `referenceStr` occurs before `compareStr`,\npositive if `referenceStr` occurs after `compareStr`, `0` if they are equivalent.\nDo not rely on exact return values of `-1` or `1`.\n\nOptionally takes `~locales` to specify locale(s) and `~options` to customize comparison behavior\n(e.g., sensitivity, case ordering, numeric sorting). These correspond to the `Intl.Collator` options.\nSee [`String.localeCompare`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare) on MDN.\n\n## Examples\n\n```rescript\nString.localeCompare(\"a\", \"c\") < 0.0 == true\nString.localeCompare(\"a\", \"a\") == 0.0\nString.localeCompare(\"a\", \"b\", ~locales=[\"en-US\"]) < 0.0 == true\nString.localeCompare(\"a\", \"A\", ~locales=[\"en-US\"], ~options={sensitivity: #base}) == 0.0\n```"
         ],
-        "signature": "let localeCompare: (string, string) => float"
+        "signature": "let localeCompare: (\n  string,\n  string,\n  ~locales: array<string>=?,\n  ~options: Intl_Collator.options=?,\n) => float"
       },
       {
         "id": "Stdlib.String.ignore",

e2e/Navigation.cy.res

@@ -0,0 +1,213 @@
+open Cy
+
+// Wait for the app to fully hydrate before interacting with links.
+// The production build is pre-rendered so React must attach event
+// handlers before client-side navigation works.
+let waitForHydration = () => {
+  getByTestId("navbar-primary")->shouldBeVisible->ignore
+  cyWindow()->its("document.readyState")->shouldWithValue("eq", "complete")->ignore
+  wait(2000)
+}
+
+// Use short, re-queryable selectors to avoid detached DOM issues.
+// When React re-renders during navigation, long chains can hold
+// references to stale elements. Separate cy.get() calls let Cypress
+// re-query from the DOM root on each retry.
+
+let clickNavLink = (~testId, ~text) => {
+  get(`[data-testid="${testId}"] a:visible`)
+  ->containsChainable(text)
+  ->click
+  ->ignore
+}
+
+let clickMobileNavLink = text => {
+  get(`[data-testid="mobile-nav"] a:visible`)
+  ->containsChainable(text)
+  ->click
+  ->ignore
+}
+
+let openMobileMenu = () => {
+  get(`[data-testid="toggle-mobile-overlay"]`)->should("be.visible")->click->ignore
+  get("#mobile-overlay")->should("be.visible")->ignore
+}
+
+// -- Desktop (1280x720) -------------------------------------------------------
+
+describe("Desktop Navigation", () => {
+  beforeEach(() => {
+    viewport(1280, 720)
+    visit("/")
+    waitForHydration()
+  })
+
+  describe("Primary navbar", () => {
+    it(
+      "should navigate to Docs via navbar link",
+      () => {
+        clickNavLink(~testId="navbar-primary-left-content", ~text="Docs")
+        url()->shouldInclude("/docs/manual/introduction")->ignore
+        get("h1")->shouldBeVisible->ignore
+      },
+    )
+
+    it(
+      "should navigate to Playground via navbar link",
+      () => {
+        clickNavLink(~testId="navbar-primary-left-content", ~text="Playground")
+        url()->shouldInclude("/try")->ignore
+      },
+    )
+
+    it(
+      "should navigate to Blog via navbar link",
+      () => {
+        clickNavLink(~testId="navbar-primary-left-content", ~text="Blog")
+        url()->shouldInclude("/blog")->ignore
+      },
+    )
+
+    it(
+      "should navigate to Community via navbar link",
+      () => {
+        clickNavLink(~testId="navbar-primary-left-content", ~text="Community")
+        url()->shouldInclude("/community")->ignore
+        get("h1")->shouldBeVisible->ignore
+      },
+    )
+
+    it(
+      "should navigate home via logo after clicking away",
+      () => {
+        clickNavLink(~testId="navbar-primary-left-content", ~text="Blog")
+        url()->shouldInclude("/blog")->ignore
+
+        get("a[aria-label='homepage']")->should("be.visible")->first->click->ignore
+        cyLocation("pathname")->shouldWithValue("eq", "/")->ignore
+      },
+    )
+  })
+
+  describe("Secondary navbar", () => {
+    it(
+      "should navigate through all secondary nav links from Docs",
+      () => {
+        // Click Docs in primary nav to reveal the secondary nav
+        clickNavLink(~testId="navbar-primary-left-content", ~text="Docs")
+        url()->shouldInclude("/docs/manual/introduction")->ignore
+
+        // Language Manual
+        clickNavLink(~testId="navbar-secondary", ~text="Language Manual")
+        url()->shouldInclude("/docs/manual/introduction")->ignore
+
+        // API
+        clickNavLink(~testId="navbar-secondary", ~text="API")
+        url()->shouldInclude("/docs/manual/api")->ignore
+
+        // Syntax Lookup
+        clickNavLink(~testId="navbar-secondary", ~text="Syntax Lookup")
+        url()->shouldInclude("/syntax-lookup")->ignore
+
+        // React
+        clickNavLink(~testId="navbar-secondary", ~text="React")
+        url()->shouldInclude("/docs/react/introduction")->ignore
+      },
+    )
+  })
+})
+
+// -- Mobile (375x667) ---------------------------------------------------------
+
+describe("Mobile Navigation", () => {
+  beforeEach(() => {
+    viewport(375, 667)
+    visit("/")
+    waitForHydration()
+  })
+
+  describe("Primary navbar", () => {
+    it(
+      "should navigate to Docs via navbar link",
+      () => {
+        clickNavLink(~testId="navbar-primary-left-content", ~text="Docs")
+        url()->shouldInclude("/docs/manual/introduction")->ignore
+        get("h1")->shouldBeVisible->ignore
+      },
+    )
+
+    it(
+      "should navigate home via logo after clicking away",
+      () => {
+        clickNavLink(~testId="navbar-primary-left-content", ~text="Docs")
+        url()->shouldInclude("/docs/manual/introduction")->ignore
+
+        get("a[aria-label='homepage']")->should("be.visible")->first->click->ignore
+        cyLocation("pathname")->shouldWithValue("eq", "/")->ignore
+      },
+    )
+  })
+
+  describe("Mobile overlay navigation", () => {
+    it(
+      "should navigate to Playground via mobile menu",
+      () => {
+        openMobileMenu()
+        clickMobileNavLink("Playground")
+        url()->shouldInclude("/try")->ignore
+      },
+    )
+
+    it(
+      "should navigate to Blog via mobile menu",
+      () => {
+        openMobileMenu()
+        clickMobileNavLink("Blog")
+        url()->shouldInclude("/blog")->ignore
+      },
+    )
+
+    it(
+      "should navigate to Community via mobile menu",
+      () => {
+        openMobileMenu()
+        clickMobileNavLink("Community")
+        url()->shouldInclude("/community")->ignore
+        get("h1")->shouldBeVisible->ignore
+      },
+    )
+  })
+
+  describe("Secondary navbar", () => {
+    it(
+      "should navigate through all secondary nav links from Docs",
+      () => {
+        // Click Docs in primary nav to reveal the secondary nav
+        clickNavLink(~testId="navbar-primary-left-content", ~text="Docs")
+        url()->shouldInclude("/docs/manual/introduction")->ignore
+
+        // Scroll to top so the secondary nav is visible
+        cyScrollTo("top")
+
+        // Language Manual
+        clickNavLink(~testId="navbar-secondary", ~text="Language Manual")
+        url()->shouldInclude("/docs/manual/introduction")->ignore
+
+        // API
+        cyScrollTo("top")
+        clickNavLink(~testId="navbar-secondary", ~text="API")
+        url()->shouldInclude("/docs/manual/api")->ignore
+
+        // Syntax Lookup
+        cyScrollTo("top")
+        clickNavLink(~testId="navbar-secondary", ~text="Syntax Lookup")
+        url()->shouldInclude("/syntax-lookup")->ignore
+
+        // React
+        cyScrollTo("top")
+        clickNavLink(~testId="navbar-secondary", ~text="React")
+        url()->shouldInclude("/docs/react/introduction")->ignore
+      },
+    )
+  })
+})