Integrate genType as 'TypeScript Interop' chapter into main docs

fhammerschmidt · fhammerschmidt · commit f6434e7fddef · 2024-01-12T14:54:40.000+01:00
diff --git a/data/sidebar_manual_latest.json b/data/sidebar_manual_latest.json
@@ -53,6 +53,12 @@
     "browser-support-polyfills",
     "libraries"
   ],
+  "TypeScript Interop": [
+    "gentype-introduction",
+    "gentype-getting-started",
+    "gentype-usage",
+    "gentype-supported-types"
+  ],
   "Build System": [
     "build-overview",
     "build-configuration",
diff --git a/misc_docs/syntax/decorator_gentype.mdx b/misc_docs/syntax/decorator_gentype.mdx
@@ -1,20 +1,18 @@
 ---
 id: "gentype-decorator"
-keywords: ["gentype", "decorator", "typescript", "flow"]
+keywords: ["gentype", "decorator", "typescript"]
 name: "@genType"
 summary: "This is the `@genType` decorator."
 category: "decorators"
 ---
 
-The `@genType` decorator may be used to export ReScript values and types to JavaScript, and import JavaScript values and types into ReScript. It allows seamless integration of compiled ReScript modules in existing TypeScript, Flow, or plain JavaScript codebases, without loosing type information across different type systems.
+The `@genType` decorator may be used to export ReScript values and types to JavaScript, and import JavaScript values and types into ReScript. It allows seamless integration of compiled ReScript modules in existing TypeScript, or plain JavaScript codebases, without losing type information across different type systems.
 
-[GenType](/docs/gentype/latest/introduction) is a code generation tool for automatically generating [TypeScript](https://www.typescriptlang.org/) / [Flow](https://flow.org/) type definitions, and JS runtime converters for non-shared ReScript values. It also features first-class support for [ReasonReact](https://reasonml.github.io/reason-react/) components.
-
-**Note:** This decorator requires the `gentype` npm package to be installed and configured correctly. Please refer to genType's [Getting Started](/docs/gentype/latest/getting-started) section for more details.
+[GenType](/docs/manual/latest/gentype-introduction) is a code generation tool for automatically generating [TypeScript](https://www.typescriptlang.org/) type definitions, and JS runtime converters for non-shared ReScript values. It also features first-class support for [rescript-react](/docs/react/latest/introduction) components.
 
 ### Example
 
-<CodeTab labels={["ReScript", "TypeScript Output", "Flow Output"]}>
+<CodeTab labels={["ReScript", "TypeScript Output"]}>
 
 ```res
 @genType
@@ -59,45 +57,8 @@ export const make: React.ComponentType<{
 };
 ```
 
-```js
-/**
- * @flow strict
- * @generated from MyComponent.res
- * @nolint
- */
-/* eslint-disable */
-// $FlowExpectedError: Reason checked type sufficiently
-type $any = any;
-
-// $FlowExpectedError: Reason checked type sufficiently
-import * as React from "react";
-
-const $$toRE818596289 = { Red: 0, Blue: 1 };
-
-// $FlowExpectedError: Reason checked type sufficiently
-import * as MyComponentBS from "./MyComponent.bs";
-
-export type color = "Red" | "Blue";
-
-// Type annotated function components are not checked by Flow, but typeof() works.
-const make$$forTypeof = function (_: {|
-  +color: color,
-  +name: string,
-|}): React$Node {
-  return null;
-};
-
-export type Props = {| +color: color, +name: string |};
-
-export const make: typeof make$$forTypeof = function MyComponent(Arg1: $any) {
-  const $props = { color: $$toRE818596289[Arg1.color], name: Arg1.name };
-  const result = React.createElement(MyComponentBS.make, $props);
-  return result;
-};
-```
-
 </CodeTab>
 
 ### References
 
-* [GenType](/docs/gentype/latest/introduction)
+* [GenType](/docs/manual/latest/gentype-introduction)
diff --git a/next.config.mjs b/next.config.mjs
@@ -102,6 +102,26 @@ const config = {
         destination: "/docs/manual/v10.0.0/unboxed",
         permanent: true,
       },
+      {
+        source: "/docs/gentype/latest/introduction",
+        destination: "/docs/manual/latest/gentype-introduction",
+        permanent: true,
+      },
+      {
+        source: "/docs/gentype/latest/getting-started",
+        destination: "/docs/manual/latest/gentype-getting-started",
+        permanent: true,
+      },
+      {
+        source: "/docs/gentype/latest/usage",
+        destination: "/docs/manual/latest/gentype-usage",
+        permanent: true,
+      },
+      {
+        source: "/docs/gentype/latest/supported-types",
+        destination: "/docs/manual/latest/gentype-supported-types",
+        permanent: true,
+      },
     ];
   },
 };
diff --git a/pages/docs/manual/latest/gentype-getting-started.mdx b/pages/docs/manual/latest/gentype-getting-started.mdx
@@ -1,10 +1,10 @@
 ---
 title: "Getting Started"
 description: "How to get started with genType in your ReScript projects"
-canonical: "/docs/gentype/latest/getting-started"
+canonical: "/docs/manual/latest/gentype-getting-started"
 ---
 
-# Getting Started
+# GenType - Getting Started
 
 ## Setup
 
diff --git a/pages/docs/manual/latest/gentype-introduction.mdx b/pages/docs/manual/latest/gentype-introduction.mdx
@@ -1,7 +1,7 @@
 ---
 title: "Introduction"
-description: "GenType - Interoperability between ReScript and TypeScript / Flow"
-canonical: "/docs/gentype/latest/introduction"
+description: "GenType - Interoperability between ReScript and TypeScript"
+canonical: "/docs/manual/latest/gentype-introduction"
 ---
 
 # GenType
@@ -98,7 +98,7 @@ const App = () => {
 
 That's it for our quick example.
 
-For detailed information, head to the [Getting Started](getting-started) or [Usage](usage) section.
+For detailed information, head to the [Getting Started](/docs/manual/latest/gentype-getting-started) or [Usage](/docs/manual/latest/gentype-usage) section.
 
 ## Development
 
diff --git a/pages/docs/manual/latest/gentype-supported-types.mdx b/pages/docs/manual/latest/gentype-supported-types.mdx
@@ -1,10 +1,10 @@
 ---
 title: "Supported Types"
-description: "Supported types and value convertion in GenType"
-canonical: "/docs/gentype/latest/supported-types"
+description: "Supported types and value conversion in GenType"
+canonical: "/docs/manual/latest/gentype-supported-types"
 ---
 
-# Supported Types
+# GenType - Supported Types
 
 <Intro>
 
@@ -39,7 +39,7 @@ The JS values are identical: there is no conversion unless the argument type nee
 
 ReScript record values of type e.g. `{x: int}` such as `{x: 0}`, `{x: 1}`, are exported to JS values of type `{x: number}` without runtime conversion.
 
-Since records are immutable by default, their fields will be exported to readonly property types in Flow/TS. Mutable fields are specified in ReScript by e.g. `{mutable mutableField: string}`.
+Since records are immutable by default, their fields will be exported to readonly property types in TS. Mutable fields are specified in ReScript by e.g. `{mutable mutableField: string}`.
 
 The `@as` annotation can be used to change the name of a field on the JS side of things. So e.g. `{@as("y") x: int}` is exported as JS type `{y: number}`.
 
@@ -50,14 +50,14 @@ If one field of the ReScript record has option type, this is exported to an opti
 ReScript object values of type e.g. `{. "x":int}` such as `{"x": 0}`, `{"x": 1}`, `{"x": 2}`, are exported as identical JS object values `{x:0}`, `{x:1}`, `{x:2}`. This requires no conversion. So they are exported to JS values of type `{x:number}`.
 A conversion is required only when the type of some field requires conversions.
 
-Since objects are immutable by default, their fields will be exported to readonly property types in Flow/TS. Mutable fields are specified in ReScript by e.g. `{ @set "mutableField": string }`.
+Since objects are immutable by default, their fields will be exported to readonly property types in TS. Mutable fields are specified in ReScript by e.g. `{ @set "mutableField": string }`.
 
 It is possible to mix object and option types, so for example the ReScript type `{. "x":int, "y":option<string>}` exports to JS type `{x:number, ?y: string}`, requires no conversion, and allows option pattern matching on the ReScript side.
 
 ## Tuples
 
 ReScript tuple values of type e.g. `(int, string)` are exported as identical JS values of type `[number, string]`. This requires no conversion, unless one of types of the tuple items does.
-While the type of ReScript tuples is immutable, there's currently no mature enforcement in TS/Flow, so they're currenty exported to mutable tuples.
+While the type of ReScript tuples is immutable, there's currently no mature enforcement in TS, so they're currenty exported to mutable tuples.
 
 ## Variants
 
@@ -96,7 +96,7 @@ Arrays with elements of ReScript type `t` are exported to JS arrays with element
 
 Immutable arrays are supported with the additional ReScript library
 [ImmutableArray.res/.resi](https://github.com/reason-association/genType/tree/master/examples/typescript-react-example/src/ImmutableArray.resi), which currently needs to be added to your project.
-The type `ImmutableArray.t<+'a>` is covariant, and is mapped to readonly array types in TS/Flow. As opposed to TS/Flow, `ImmutableArray.t` does not allow casting in either direction with normal arrays. Instead, a copy must be performed using `fromArray` and `toArray`.
+The type `ImmutableArray.t<+'a>` is covariant, and is mapped to readonly array types in TS. As opposed to TS, `ImmutableArray.t` does not allow casting in either direction with normal arrays. Instead, a copy must be performed using `fromArray` and `toArray`.
 
 ## Functions and Function Components
 
@@ -117,7 +117,7 @@ let make = (~name) => React.string(name);
 
 ## Imported Types
 
-It's possible to import an existing TS/Flow type as an opaque type in ReScript. For example,
+It's possible to import an existing TS type as an opaque type in ReScript. For example,
 
 ```res
 @genType.import("./SomeFlowTypes") type weekday
diff --git a/pages/docs/manual/latest/gentype-usage.mdx b/pages/docs/manual/latest/gentype-usage.mdx
@@ -1,4 +1,10 @@
-# Usage
+---
+title: "Usage"
+description: "GenType - Interoperability between ReScript and TypeScript"
+canonical: "/docs/manual/latest/gentype-usage"
+---
+
+# GenType Usage
 
 <Intro>
 
diff --git a/pages/docs/manual/latest/shared-data-types.mdx b/pages/docs/manual/latest/shared-data-types.mdx
@@ -41,4 +41,4 @@ Unlike most compiled-to-js languages, in ReScript, **you don't need to write dat
 
 Many of these are stable, which means that you can still serialize/deserialize them as-is without manual conversions. But we discourage actively peeking into their structure otherwise.
 
-These types require manual conversions if you want to export them for JS consumption. For a seamless JS/TypeScript/Flow integration experience, you might want to use [genType](https://github.com/cristianoc/gentype) instead of doing conversions by hand.
+These types require manual conversions if you want to export them for JS consumption. For a seamless JS/TypeScript integration experience, you might want to use [genType](https://github.com/cristianoc/gentype) instead of doing conversions by hand.
diff --git a/pages/docs/manual/v10.0.0/build-configuration.mdx b/pages/docs/manual/v10.0.0/build-configuration.mdx
@@ -161,7 +161,7 @@ Generating JS files with the `.bs.js` suffix means that, on the JS side, you can
 - It's immediately clear that we're dealing with a generated JS file here.
 - It avoids clashes with a potential `theFile.js` file in the same folder.
 - It avoids the need of using a build system loader for ReScript files. This + in-source build means integrating a ReScript project into your pure JS codebase **basically doesn't touch anything in your build pipeline at all**.
-- [genType](/docs/gentype/latest/introduction) requires `bs.js` for compiled JS artifacts. If you are using `genType`, you need to use `bs.js` for now.
+- [genType](/docs/manual/latest/gentype-introduction) requires `bs.js` for compiled JS artifacts. If you are using `genType`, you need to use `bs.js` for now.
 
 ## warnings
 
diff --git a/pages/docs/manual/v9.0.0/build-configuration.mdx b/pages/docs/manual/v9.0.0/build-configuration.mdx
@@ -157,7 +157,7 @@ Generating JS files with the `.bs.js` suffix means that, on the JS side, you can
 - It's immediately clear that we're dealing with a generated JS file here.
 - It avoids clashes with a potential `theFile.js` file in the same folder.
 - It avoids the need of using a build system loader for ReScript files. This + in-source build means integrating a ReScript project into your pure JS codebase **basically doesn't touch anything in your build pipeline at all**.
-- [genType](/docs/gentype/latest/introduction) requires `bs.js` for compiled JS artifacts. If you are using `genType`, you need to use `bs.js` for now.
+- [genType](/docs/manual/latest/gentype-introduction) requires `bs.js` for compiled JS artifacts. If you are using `genType`, you need to use `bs.js` for now.
 
 ## warnings
 
diff --git a/pages/docs/react/latest/introduction.mdx b/pages/docs/react/latest/introduction.mdx
@@ -18,7 +18,7 @@ All our documented examples can be compiled in our [ReScript Playground](/try) a
 - Comes with all essential React APIs for building production ready apps (`useState`, `useReducer`, `useEffect`, `useRef`,...)
 - No component class API (all ReScript & React codebases are built on function components & hooks)
 - Strong level of type safety and type inference for component props and state values
-- [GenType](/docs/gentype/latest/introduction) support for importing / exporting React components in TypeScript codebases
+- [GenType](/docs/manual/latest/gentype-introduction) support for importing / exporting React components in TypeScript codebases
 
 > **This documentation assumes basic knowledge about ReactJS.**
 >
diff --git a/pages/docs/react/v0.10.0/introduction.mdx b/pages/docs/react/v0.10.0/introduction.mdx
@@ -18,13 +18,13 @@ All our documented examples can be compiled in our [ReScript Playground](/try) a
 - Comes with all essential React APIs for building production ready apps (`useState`, `useReducer`, `useEffect`, `useRef`,...)
 - No component class API (all ReScript & React codebases are built on functional components & hooks)
 - Strong level of type safety and type inference for component props and state values
-- [GenType](/docs/gentype/latest/introduction) support for importing / exporting React components in Flow and TypeScript codebases
+- [GenType](/docs/manual/latest/gentype-introduction) support for importing / exporting React components in Flow and TypeScript codebases
 
 > **This documentation assumes basic knowledge about ReactJS.**
 >
 > Please note that even though we will cover many basic React concepts, it might still be necessary to have a look at the official [ReactJS](https://reactjs.org) resources, especially if you are a complete beginner with React.
 
 ## Development
 
- - In case you are having any issues or if you want to help us out improving our bindings, check out our [rescript-react GitHub repository](https://github.com/rescript-lang/rescript-react).
+- In case you are having any issues or if you want to help us out improving our bindings, check out our [rescript-react GitHub repository](https://github.com/rescript-lang/rescript-react).
 - For doc related issues, please go to the [rescript-lang.org repo](https://github.com/reason-association/rescript-lang.org).
diff --git a/pages/docs/react/v0.11.0/introduction.mdx b/pages/docs/react/v0.11.0/introduction.mdx
@@ -18,7 +18,7 @@ All our documented examples can be compiled in our [ReScript Playground](/try) a
 - Comes with all essential React APIs for building production ready apps (`useState`, `useReducer`, `useEffect`, `useRef`,...)
 - No component class API (all ReScript & React codebases are built on function components & hooks)
 - Strong level of type safety and type inference for component props and state values
-- [GenType](/docs/gentype/latest/introduction) support for importing / exporting React components in TypeScript codebases
+- [GenType](/docs/manual/latest/gentype-introduction) support for importing / exporting React components in TypeScript codebases
 
 > **This documentation assumes basic knowledge about ReactJS.**
 >
diff --git a/scripts/extract-tocs.mjs b/scripts/extract-tocs.mjs
@@ -274,32 +274,6 @@ const createReactToc = (version) => {
   fs.writeFileSync(TARGET_FILE, JSON.stringify(toc), "utf8");
 };
 
-const createGenTypeToc = () => {
-  const MD_DIR = path.join(__dirname, "../pages/docs/gentype/latest");
-  const SIDEBAR_JSON = path.join(
-    __dirname,
-    "../data/sidebar_gentype_latest.json"
-  );
-  const TARGET_FILE = path.join(
-    __dirname,
-    "../index_data/gentype_latest_toc.json"
-  );
-
-  const sidebarJson = JSON.parse(fs.readFileSync(SIDEBAR_JSON));
-
-  const FILE_ORDER = Object.values(sidebarJson).reduce((acc, items) => {
-    return acc.concat(items);
-  }, []);
-
-  const files = glob.sync(`${MD_DIR}/*.?(js|md?(x))`);
-  const ordered = orderFiles(files, FILE_ORDER);
-
-  const result = ordered.map((filepath) => processFile(filepath, sidebarJson));
-  const toc = createTOC(result);
-
-  fs.writeFileSync(TARGET_FILE, JSON.stringify(toc), "utf8");
-};
-
 const createCommunityToc = () => {
   const MD_DIR = path.join(__dirname, "../pages/community");
   const SIDEBAR_JSON = path.join(__dirname, "../data/sidebar_community.json");
@@ -344,5 +318,4 @@ createReasonCompilerToc();
 createReactToc("latest");
 createReactToc("v0.10.0");
 createReactToc("v0.11.0");
-createGenTypeToc();
 createCommunityToc();
diff --git a/src/DocsOverview.res b/src/DocsOverview.res
@@ -36,7 +36,7 @@ let default = (~showVersionSelect=true) => {
   let ecosystem = [
     ("Package Index", "/packages"),
     ("rescript-react", "/docs/react/latest/introduction"),
-    ("GenType", "/docs/gentype/latest/introduction"),
+    ("GenType", "/docs/manual/latest/gentype-introduction"),
     ("Reanalyze", "https://github.com/reason-association/reanalyze"),
   ]
 
diff --git a/src/common/App.res b/src/common/App.res
@@ -131,8 +131,6 @@ let make = (props: props): React.element => {
     }
   | {base: ["docs", "reason-compiler"], version: Latest} =>
     <ReasonCompilerDocsLayout> content </ReasonCompilerDocsLayout>
-  | {base: ["docs", "gentype"], version: Latest} =>
-    <GenTypeDocsLayout frontmatter={component->frontmatter}> content </GenTypeDocsLayout>
   // common routes
   | {base} =>
     switch Belt.List.fromArray(base) {
diff --git a/src/common/Constants.res b/src/common/Constants.res
@@ -20,7 +20,7 @@ let languageManual = version => {
 let ecosystem = [
   ("Package Index", "/packages"),
   ("rescript-react", "/docs/react/latest/introduction"),
-  ("GenType", "/docs/gentype/latest/introduction"),
+  ("GenType", "/docs/manual/latest/gentype-introduction"),
   ("Reanalyze", "https://github.com/reason-association/reanalyze"),
 ]
 
diff --git a/src/components/Navigation.res b/src/components/Navigation.res
@@ -168,8 +168,8 @@ module DocsSection = {
         description: "Reference for all language features",
         href: `/docs/manual/${version}/introduction`,
         isActive: url => {
-          switch url.base {
-          | ["docs", "manual"] => true
+          switch url.fullpath {
+          | ["docs", "manual", _, fragment] => !(fragment->Js.String2.startsWith("gentype"))
           | _ => false
           }
         },
@@ -189,11 +189,11 @@ module DocsSection = {
       {
         imgSrc: "/static/ic_gentype@2x.png",
         title: "GenType",
-        description: "Seamless TypeScript & Flow integration",
-        href: "/docs/gentype/latest/introduction",
+        description: "Seamless TypeScript integration",
+        href: "/docs/manual/latest/gentype-introduction",
         isActive: url => {
-          switch url.base {
-          | ["docs", "gentype"] => true
+          switch url.fullpath {
+          | ["docs", "manual", _, fragment] => fragment->Js.String2.startsWith("gentype")
           | _ => false
           }
         },
diff --git a/src/layouts/GenTypeDocsLayout.res b/src/layouts/GenTypeDocsLayout.res
diff --git a/src/layouts/GenTypeDocsLayout.resi b/src/layouts/GenTypeDocsLayout.resi
diff --git a/src/layouts/LandingPageLayout.res b/src/layouts/LandingPageLayout.res

Original file line number	Diff line number	Diff line change
`@@ -41,4 +41,4 @@ Unlike most compiled-to-js languages, in ReScript, **you don't need to write dat`
`41`	`41`
`42`	`42`	`Many of these are stable, which means that you can still serialize/deserialize them as-is without manual conversions. But we discourage actively peeking into their structure otherwise.`
`43`	`43`
`44`		`-These types require manual conversions if you want to export them for JS consumption. For a seamless JS/TypeScript/Flow integration experience, you might want to use [genType](https://github.com/cristianoc/gentype) instead of doing conversions by hand.`
	`44`	`+These types require manual conversions if you want to export them for JS consumption. For a seamless JS/TypeScript integration experience, you might want to use [genType](https://github.com/cristianoc/gentype) instead of doing conversions by hand.`