Document getTransformOptions

Summary:
We had a stub entry for `getTransformOptions` in the docs, but it contained zero information. This diff is an attempt to document it as-is; we'll likely want to remove/simplify some of this functionality later.

Closes #845.

This diff also introduces some new(-to-Metro) formatting and styling to support the relatively complex content:

* A "deprecated" label, with CSS mostly lifted from the React Native website's implementation of platform labels.
  * The styling for `li .label` is all new.
* The use of a bulleted list to document a function's parameters.
* The use of nested bulleted lists to document complex object types.
* The use of Flow code blocks to show ancillary type definitions under the relevant config option.

Reviewed By: huntie

Differential Revision: D41400599

fbshipit-source-id: 061cc896fdb3fec9948c4045123d6c05e0d5cc81

docs/Configuration.md

@@ -111,11 +111,11 @@ Type: `string`
 
 The path to the `metro-file-map` cache directory, defaults to `os.tmpdir()`.
 
-#### Deprecated: `hasteMapCacheDirectory`
+#### `hasteMapCacheDirectory` <div class="label deprecated">Deprecated</div>
 
 Type: `string`
 
-Alias of `fileMapCacheDirectory`
+Alias of [`fileMapCacheDirectory`](#filemapcachedirectory)
 
 ---
 ### Resolver Options
@@ -277,9 +277,55 @@ runtime in the app's node modules confugration.
 
 #### `getTransformOptions`
 
-Type: `GetTransformOptions`
+Type: Function (see details below)
 
-Get the transform options.
+A function called by Metro to calculate additional options for the transformer and serializer based on the specific bundle being built.
+
+Metro expects `getTransformOptions` to have the following signature:
+
+```flow
+function getTransformOptions(
+  entryPoints: $ReadOnlyArray<string>,
+  options: {
+    dev: boolean,
+    hot: boolean,
+    platform: ?string,
+  },
+  getDependenciesOf: (path: string) => Promise<Array<string>>,
+): Promise<ExtraTransformOptions> {
+  // ...
+}
+```
+
+`getTransformOptions` receives these parameters:
+
+* **`entryPoints`**: Absolute paths to the bundle's entry points (typically just one).
+* **`options`**:
+  * **`dev`**: Whether the bundle is being built in development mode.
+  * **`hot`**: <div class="label deprecated">Deprecated</div> Always true.
+  * **`platform`**: The target platform (e.g. `ios`, `android`).
+* **`getDependenciesOf`**: A function which, given an absolute path to a module, returns a promise that resolves to the absolute paths of the module's transitive dependencies.
+
+`getTransformOptions` should return a promise that resolves to an object with the following properties:
+
+```flow
+type ExtraTransformOptions = {
+  preloadedModules?: {[path: string]: true} | false,
+  ramGroups?: Array<string>,
+  transform?: {
+    inlineRequires?: {blockList: {[string]: true}} | boolean,
+    nonInlinedRequires?: $ReadOnlyArray<string>,
+  },
+};
+```
+
+* **`preloadedModules`**: A plain object whose keys represent a set of absolute paths. When serializing an [indexed RAM bundle](https://reactnative.dev/docs/ram-bundles-inline-requires#enable-the-ram-format), the modules in this set will be marked for eager evaluation at runtime.
+* **`ramGroups`**: An array of absolute paths. When serializing an [indexed RAM bundle](https://reactnative.dev/docs/ram-bundles-inline-requires#enable-the-ram-format), each of the listed modules will be serialized along with its transitive dependencies. At runtime, the modules will all be parsed together as soon as any one of them is evaluated.
+* **`transform`**: Advanced options for the transformer.
+  * **`inlineRequires`**:
+    * If `inlineRequires` is a boolean, it controls whether [inline requires](https://reactnative.dev/docs/ram-bundles-inline-requires#inline-requires) are enabled in this bundle.
+    * If `inlineRequires` is an object, inline requires are enabled in all modules, except ones whose absolute paths appear as keys of `inlineRequires.blockList`.
+  * **`nonInlinedRequires`**: An array of unresolved module specifiers (e.g. `react`, `react-native`) to never inline, even when inline requires are enabled.
 
 #### `hermesParser`
 
@@ -324,7 +370,7 @@ Where to fetch the assets from.
 
 #### `getRunModuleStatement`
 
-Type: `(number` &#x7c; `string) => string`
+Type: `(number | string) => string`
 
 Specify the format of the initial require statements that are appended at the end of the bundle. By default is `__r(${moduleId});`.
 

website/docusaurus.config.js

@@ -139,6 +139,9 @@ const siteConfig = {
       appId: 'T38HJZTD87',
       indexName: 'metro',
     },
+    prism: {
+      additionalLanguages: ['flow'],
+    },
   },
   scripts: ['https://buttons.github.io/buttons.js'],
 };

website/src/css/custom.scss

@@ -21,6 +21,7 @@
   --ifm-color-primary-lighter: #f36c6c;
   --ifm-color-primary-lightest: #f69696;
   --ifm-code-font-size: 95%;
+  --text: #1a1a1a;
 }
 
 /* Announcement banner */
@@ -33,3 +34,178 @@ div[class^="announcementBarContent"] {
     }
   }
 }
+
+
+/* Labels */
+
+.label {
+  display: inline-block;
+  position: relative;
+  font-size: 0.85rem;
+  font-weight: 500;
+  color: #fff;
+  padding: 2px 12px;
+  border-radius: 0 2px 2px 0;
+
+  /* Label sharp end */
+  &:before {
+    content: "";
+    position: absolute;
+    top: 0;
+    left: -12px;
+    border-color: transparent;
+    border-style: solid;
+    border-width: 12px 12px 12px 0;
+  }
+
+  /* Label skeuomorphic hole */
+  &:after {
+    content: "";
+    position: absolute;
+    top: 10px;
+    left: 0;
+    width: 4px;
+    height: 4px;
+    border-radius: 2px;
+    background: #fff;
+  }
+
+  /* Basic label */
+  &.basic {
+    border-radius: 3px;
+    border-style: solid;
+    border-width: 2px;
+
+    &:before,
+    &:after {
+      display: none;
+    }
+  }
+
+  /* Label variants */
+  &.deprecated {
+    background: #888;
+
+    &:before {
+      border-right-color: #888;
+    }
+  }
+
+  &.required {
+    margin-left: 0;
+    margin-right: 16px;
+    color: #fa5035;
+    border-color: #fa5035;
+  }
+}
+
+html[data-theme="dark"] .label {
+  color: var(--text);
+
+  &:after {
+    background: var(--ifm-background-color);
+  }
+
+  &.deprecated {
+    background: #ccc;
+
+    &:before {
+      border-right-color: #ccc;
+    }
+  }
+
+  &.required {
+    color: #fa5035;
+  }
+}
+
+/* Label inside other tags */
+
+li .label {
+  margin-left: 10px;
+  margin-right: 2px;
+  padding: 0px 10px;
+  height: 20px;
+  line-height: 20px;
+  &:before {
+    left: -10px;
+    border-width: 10px 10px 10px 0px;
+  }
+  &:after {
+    top: 8px;
+  }
+}
+
+h2 .label {
+  top: -6px;
+  margin-left: 12px;
+  padding: 3px 12px;
+}
+
+h3 .label {
+  top: -3px;
+  margin-left: 22px;
+  line-height: 20px;
+}
+
+h4 .label {
+  margin-left: 16px;
+  line-height: 20px;
+}
+
+td .label {
+  padding: 0 8px 0 10px;
+  font-size: 0.7rem;
+  margin-left: 14px;
+
+  &:before {
+    left: -8px;
+    border-width: 10px 8px 10px 0;
+  }
+
+  &:after {
+    top: 8px;
+  }
+
+  &.required {
+    margin-left: 8px;
+    letter-spacing: 0.02rem;
+    padding: 0 6px;
+    border-width: 1px;
+    margin-right: 0;
+  }
+
+  &.two-lines {
+    margin-left: 0;
+    margin-top: 5px;
+  }
+}
+
+/* Label as dot in the right sidebar */
+
+.table-of-contents .label {
+  position: absolute;
+  padding: 0;
+  width: 6px;
+  height: 6px;
+  border-radius: 100%;
+  margin-left: 4px;
+  margin-top: 7px;
+  white-space: nowrap;
+  overflow: hidden;
+  color: transparent;
+  float: initial;
+
+  &.required {
+    position: initial;
+    margin-left: 0;
+    margin-right: 6px;
+    border-width: 3px;
+    background: #fa5035;
+  }
+
+  /* Second dot shift */
+  &:nth-child(3) {
+    margin-left: 13px;
+  }
+}