Add a sample / cheet-sheat of conditional compilation directives (#1430)

Author: prprabhu-ms

change/@internal-acs-ui-common-7d89b41a-63c7-45c1-8aac-dcdfde00a4e3.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Add sample module for conditional compilation",
+  "packageName": "@internal/acs-ui-common",
+  "email": "82062616+prprabhu-ms@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

packages/acs-ui-common/package.json

@@ -31,7 +31,8 @@
     "@azure/communication-common": "1.0.0"
   },
   "peerDependencies": {
-    "react": ">=16.8.0 <18.0.0"
+    "react": ">=16.8.0 <18.0.0",
+    "@types/react": ">=16.8.0 <18.0.0"
   },
   "devDependencies": {
     "@babel/cli": "~7.16.0",

packages/acs-ui-common/src/conditional-compilation-sample/index.tsx

@@ -0,0 +1,252 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import React from 'react';
+
+/**
+ * This folder contains some simple examples using conditional compilation directive.
+ *
+ * They are intended to be a cheet-sheat when you're trying to figure out how to make conditional compilation work for you.
+ *
+ * Just like the rest of the code in this repository, this module can be built for both flavored builds:
+ *
+ * To build for beta (i.e. without any code removed by conditional compilation):
+ *
+ * ```bash
+ *   rush switch-flavor:beta  # This is also the default
+ *   rush build -t .
+ * ``
+ *
+ * To build for stable (i.e. marked code conditionally removed):
+ *
+ * ```bash
+ *   rush switch-flavor:stable
+ *   rush build -t .
+ * ```
+ *
+ * In the latter case, you can see the transformed code in `packages/acs-ui-common/preprocessed/conditional-compilation-sample/`.
+ *
+ * General guidelines:
+ * 1. Keep conditional compilation as small as possible.
+ * 2. Keep conditional compilation encapsulated.
+ * 3. Keep conditional compilation near package boundary.
+ *   a. If the conditional compilation is in our exported API, try to quickly convert to a type that is not conditional.
+ *      This will often simplify implementation.
+ *   b. If the conditional compilation is to deal with a dependency, try to quickly fill in a default value so that you
+ *      don't need conditional compilation at point-of-use.
+ *
+ * (1) is not always possible (depends on the feature you're working on), but (3) can help you make the footprint smaller, and
+ * (2) can help you keep the footprint sane.
+ *
+ * Organization of this file:
+ * - First let's talk types
+ * - Then let's talk conditional business logic
+ * - Finally, let's bring those together in some repeated patterns we see in this code-base.
+ */
+
+/* eslint-disable jsdoc/require-jsdoc */
+
+/******************************************************************************
+ *
+ * Conditional types
+ *
+ */
+
+/**
+ * Conditionally define a type or interface.
+ */
+/* @conditional-compile-remove-from(stable) */
+type A = number;
+
+/* @conditional-compile-remove-from(stable) */
+interface B {
+  c: number;
+}
+
+/**
+ * Conditionally import from a package.
+ */
+/* @conditional-compile-remove-from(stable) */
+import { Dir } from 'fs';
+
+/**
+ * Conditionally export from a module.
+ */
+/* @conditional-compile-remove-from(stable) */
+export interface C {
+  a: A;
+  b: B;
+}
+
+/* @conditional-compile-remove-from(stable) */
+export type MyDir = Dir;
+
+/**
+ * Conditionally add fields to an interface
+ */
+export interface B2 {
+  sameOld: number;
+  /* @conditional-compile-remove-from(stable) */
+  somethingNew: number;
+}
+
+/**
+ * Conditionally add variants to a type union
+ *
+ * Watchout: A common pitfall here is adding the conditional directive before the binary operator.
+ */
+export type Unionize = number | /* @conditional-compile-remove-from(stable) */ boolean;
+export type Impossible = number & /* @conditional-compile-remove-from(stable) */ boolean;
+
+/**
+ * Add a parameter to an existing function
+ *
+ * We do not support adding a parameter to a function _implementation_ signature.
+ * But we do support conditional parameters in function overload signature.
+ *
+ * So there are two ways to achieve this:
+ * - Add a single overload signature with conditional parameter: `f` in the example.
+ * - Add a new overload signature with conditional paramter: `f` and `g` in the example.
+ *
+ * In each case, you must modify the implementation signature to satisfy all the overloads.
+ * The example does this by adding `f` and `g` as optional parameters.
+ *
+ * cf: https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads.
+ */
+export function d(e: number, /* @conditional-compile-remove-from(stable) */ f: number): void;
+/* @conditional-compile-remove-from(stable) */
+export function d(e: number, f: number, g: number): void;
+export function d(e: number, f?: number, g?: number) {
+  console.log(e);
+  /* @conditional-compile-remove-from(stable) */
+  console.log(f, g);
+}
+
+/******************************************************************************
+ *
+ * Conditional business logic
+ *
+ */
+
+/**
+ * Call a function with conditional parameters.
+ */
+export function dCaller() {
+  d(1, /* @conditional-compile-remove-from(stable) */ 2);
+  d(1, /* @conditional-compile-remove-from(stable) */ 2, /* @conditional-compile-remove-from(stable) */ 3);
+
+  // The following would stable flavor build because the function overload signature for `d` only allows one
+  // argument in stable flavor.
+  // d(1, 2, 3);
+}
+
+/**
+ * Conditional inclusion of JSX components can be a bit tricky, because we must remove partial expressions.
+ */
+export function GottaHaveAnExtraStackItem(): JSX.Element {
+  return (
+    <ul>
+      <li>Old kid</li>
+      {/* @conditional-compile-remove-from(stable) */ <li>New Kid</li>}
+    </ul>
+  );
+}
+
+/**
+ * Conditionally modify props passed to JSX components.
+ *
+ * It's best to recast this as a conditional variable assignment.
+ */
+export function OverrideSomePropInBeta(): JSX.Element {
+  const flavorDependentProp = propTrampoline();
+  return <h1 className={flavorDependentProp}>Nothing to see here!</h1>;
+}
+function propTrampoline() {
+  let propValue = 'general';
+  /* @conditional-compile-remove-from(stable) */
+  propValue = 'II class';
+  return propValue;
+}
+
+/******************************************************************************
+ *
+ * Common complex patterns
+ *
+ */
+
+/**
+ * A common example where a combination of some of the examples above is required is extending a selector.
+ *
+ * Note how the selector has a conditional field in the *return type* and the *implementation*, but does not have a conditional
+ * dependency (and hence no conditional argument). This follows from the principle that conditional compilation should be restricted
+ * to be as close to the API boundary as possible -- we require the selector's type to not include the new field in stable flavored builds,
+ * but there is no reason that the internal argument list can't contain the extra (and unused) dependency on a new selector.
+ */
+export type MyExtensibleSelector = (
+  state: DummyState,
+  props: DummyProps
+) => {
+  memoizedA: boolean;
+  memoizedB: boolean;
+  /* @conditional-compile-remove-from(stable) */
+  memoizedC: boolean;
+};
+
+export const myExtensibleSelector: MyExtensibleSelector = dummyCreateSelector(
+  [memoizedBoolean, memoizedBoolean, memoizedBoolean],
+  (a, b, c) => {
+    return {
+      memoizedA: a,
+      memoizedB: b,
+      /* @conditional-compile-remove-from(stable) */
+      memoizedC: c
+    };
+  }
+);
+
+/******************************************************************************
+ *
+ * Some helpers needed for examples above.
+ *
+ * No conditional compilation examples below this.
+ */
+
+type DummyState = unknown;
+type DummyProps = unknown;
+function memoizedBoolean(state: DummyState, props: DummyProps) {
+  console.log(state, props);
+  return true;
+}
+
+function dummyCreateSelector(
+  dependencySelectors: [
+    (state: DummyState, props: DummyProps) => boolean,
+    (state: DummyState, props: DummyProps) => boolean,
+    (state: DummyState, props: DummyProps) => boolean
+  ],
+  func: (a: boolean, b: boolean, c: boolean) => { memoizedA: boolean; memoizedB: boolean; memoizedC: boolean }
+): (state: DummyState, props: DummyProps) => { memoizedA: boolean; memoizedB: boolean; memoizedC: boolean };
+function dummyCreateSelector(
+  dependencySelectors: [
+    (state: DummyState, props: DummyProps) => boolean,
+    (state: DummyState, props: DummyProps) => boolean,
+    (state: DummyState, props: DummyProps) => boolean
+  ],
+  func: (a: boolean, b: boolean, c: boolean) => { memoizedA: boolean; memoizedB: boolean }
+): (state: DummyState, props: DummyProps) => { memoizedA: boolean; memoizedB: boolean };
+function dummyCreateSelector(
+  dependencySelectors: [
+    (state: DummyState, props: DummyProps) => boolean,
+    (state: DummyState, props: DummyProps) => boolean,
+    (state: DummyState, props: DummyProps) => boolean
+  ],
+  func: (a: boolean, b: boolean, c: boolean) => unknown
+) {
+  return (state: DummyState, props: DummyProps) => {
+    return func(
+      dependencySelectors[0](state, props),
+      dependencySelectors[1](state, props),
+      dependencySelectors[2](state, props)
+    );
+  };
+}