Started adopting api-extractor

theatre/core/devEnv/api-extractor.json

@@ -0,0 +1,39 @@
+/**
+ * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  /**
+   * Optionally specifies another JSON config file that this file extends from.  This provides a way for
+   * standard settings to be shared across multiple projects.
+   *
+   * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
+   * the "extends" field.  Otherwise, the first path segment is interpreted as an NPM package name, and will be
+   * resolved using NodeJS require().
+   *
+   * SUPPORTED TOKENS: none
+   * DEFAULT VALUE: ""
+   */
+  "extends": "../../../devEnv/api-extractor-base.json",
+  // "extends": "my-package/include/api-extractor-base.json"
+
+  "mainEntryPointFilePath": "../../.temp/declarations/core/src/index.d.ts",
+  "bundledPackages": ["@theatre/core", "@theatre/shared"],
+
+  /**
+   * Determines the "<projectFolder>" token that can be used with other config file settings.  The project folder
+   * typically contains the tsconfig.json and package.json config files, but the path is user-defined.
+   *
+   * The path is resolved relative to the folder of the config file that contains the setting.
+   *
+   * The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
+   * parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
+   * that contains a tsconfig.json file.  If a tsconfig.json file cannot be found in this way, then an error
+   * will be reported.
+   *
+   * SUPPORTED TOKENS: <lookup>
+   * DEFAULT VALUE: "<lookup>"
+   */
+  "projectFolder": ".."
+}

theatre/core/devEnv/api-extractor.tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "paths": {
+      "@theatre/core/*": ["../../.temp/declarations/core/src/*"],
+      "@theatre/shared/*": ["../../.temp/declarations/shared/src/*"]
+    }
+  }
+}

theatre/core/src/coreExports.ts

@@ -21,8 +21,12 @@ export {types}
 /**
  * Returns a project of the given id, or creates one if it doesn't already exist.
  *
- * If @theatre/studio is also loaded, then the state of the project will be managed by the studio.
+ * @remarks
+ * If \@theatre/studio is also loaded, then the state of the project will be managed by the studio.
  *
+ * [Learn more about exporting](https://docs.theatrejs.com/in-depth/#exporting)
+ *
+ * @example
  * Usage:
  * ```ts
  * import {getProject} from '@theatre/core'
@@ -30,6 +34,7 @@ export {types}
  * const project = getProject("a-unique-id", config)
  * ```
  *
+ * @example
  * Usage with an explicit state:
  * ```ts
  * import {getProject} from '@theatre/core'
@@ -37,8 +42,6 @@ export {types}
  * const config = {state} // here the config contains our saved state
  * const project = getProject("a-unique-id", config)
  * ```
- *
- * Learn more about exporting https://docs.theatrejs.com/in-depth/#exporting
  */
 export function getProject(id: string, config: IProjectConfig = {}): IProject {
   const {...restOfConfig} = config
@@ -122,8 +125,8 @@ const validateProjectIdOrThrow = (value: string) => {
 /**
  * Calls `callback` every time the pointed value of `pointer` changes.
  *
- * @param pointer A pointer (like `object.props.x`)
- * @param callback The callback is called every time the value of pointerOrDerivation changes
+ * @param pointer - A pointer (like `object.props.x`)
+ * @param callback - The callback is called every time the value of pointerOrDerivation changes
  * @returns An unsubscribe function
  */
 export function onChange<P extends PointerType<$IntentionalAny>>(

theatre/core/src/projects/TheatreProject.ts

@@ -41,8 +41,8 @@ export interface IProject {
 
   /**
    * Creates a Sheet under the project
-   * @param sheetId Sheets are identified by their `sheetId`, which must be a string longer than 3 characters
-   * @param instanceId Optionally provide an `instanceId` if you want to create multiple instances of the same Sheet
+   * @param sheetId - Sheets are identified by their `sheetId`, which must be a string longer than 3 characters
+   * @param instanceId - Optionally provide an `instanceId` if you want to create multiple instances of the same Sheet
    * @returns The newly created Sheet
    *
    * **Docs: https://docs.theatrejs.com/in-depth/#sheets**

theatre/core/src/propTypes/index.ts

@@ -65,9 +65,6 @@ const validateCommonOpts = (
  *   {label: "Position"}
  * )
  * ```
- * @param props
- * @param opts
- * @returns
  *
  */
 export const compound = <Props extends IShorthandCompoundProps>(
@@ -122,8 +119,8 @@ export const compound = <Props extends IShorthandCompoundProps>(
  * })
  * ```
  *
- * @param defaultValue The default value (Must be a finite number)
- * @param opts The options (See usage examples)
+ * @param defaultValue - The default value (Must be a finite number)
+ * @param opts - The options (See usage examples)
  * @returns A number prop config
  */
 export const number = (
@@ -222,8 +219,8 @@ export const number = (
  * })
  * ```
  *
- * @param defaultValue The default value (must be a boolean)
- * @param opts Options (See usage examples)
+ * @param defaultValue - The default value (must be a boolean)
+ * @param opts - Options (See usage examples)
  */
 export const boolean = (
   defaultValue: boolean,
@@ -264,8 +261,8 @@ export const boolean = (
  * })
  * ```
  *
- * @param defaultValue The default value (must be a string)
- * @param opts The options (See usage examples)
+ * @param defaultValue - The default value (must be a string)
+ * @param opts - The options (See usage examples)
  * @returns A string prop type
  */
 export const string = (

theatre/package.json

@@ -13,12 +13,16 @@
     "build:js:watch": "node -r esbuild-register devEnv/watch.ts",
     "build:ts": "run-s typecheck build:ts:bundle",
     "build:ts:bundle": "rollup -c devEnv/declarations-bundler/rollup.config.js",
+    "build:api-json": "run-p build:api-json:core build:api-json:studio",
+    "build:api-json:core": "api-extractor run --local --config core/devEnv/api-extractor.json",
+    "build:api-json:studio": "api-extractor run --local --config studio/devEnv/api-extractor.json",
     "build": "run-p build:ts build:js"
   },
   "devDependencies": {
     "@babel/cli": "^7.14.3",
     "@babel/core": "^7.14.3",
     "@babel/runtime": "^7.14.0",
+    "@microsoft/api-extractor": "^7.18.11",
     "@rollup/plugin-alias": "^3.1.5",
     "@rollup/plugin-multi-entry": "^4.1.0",
     "@rollup/plugin-replace": "^2.4.2",

theatre/studio/devEnv/api-extractor.json

@@ -0,0 +1,39 @@
+/**
+ * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  /**
+   * Optionally specifies another JSON config file that this file extends from.  This provides a way for
+   * standard settings to be shared across multiple projects.
+   *
+   * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
+   * the "extends" field.  Otherwise, the first path segment is interpreted as an NPM package name, and will be
+   * resolved using NodeJS require().
+   *
+   * SUPPORTED TOKENS: none
+   * DEFAULT VALUE: ""
+   */
+  "extends": "../../../devEnv/api-extractor-base.json",
+  // "extends": "my-package/include/api-extractor-base.json"
+
+  "mainEntryPointFilePath": "../../.temp/declarations/studio/src/index.d.ts",
+  "bundledPackages": ["@theatre/studio", "@theatre/shared"],
+
+  /**
+   * Determines the "<projectFolder>" token that can be used with other config file settings.  The project folder
+   * typically contains the tsconfig.json and package.json config files, but the path is user-defined.
+   *
+   * The path is resolved relative to the folder of the config file that contains the setting.
+   *
+   * The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
+   * parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
+   * that contains a tsconfig.json file.  If a tsconfig.json file cannot be found in this way, then an error
+   * will be reported.
+   *
+   * SUPPORTED TOKENS: <lookup>
+   * DEFAULT VALUE: "<lookup>"
+   */
+  "projectFolder": ".."
+}

theatre/studio/devEnv/api-extractor.tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "paths": {
+      "@theatre/studio/*": ["../../.temp/declarations/studio/src/*"],
+      "@theatre/shared/*": ["../../.temp/declarations/shared/src/*"],
+      // not sure why it can't resolve react-icons, but we don't need it in the declarations anyway.
+      "react-icons": ["./cantResolve.ignore.ts"]
+    }
+  }
+}

theatre/studio/devEnv/cantResolve.ignore.ts

@@ -0,0 +1,7 @@
+/**
+ * For some reason, invoking api-extractor causes TS to be unable to resolve
+ * some packages (so far "react-icons"). This module is a replacement for those.
+ *
+ * Check ./api-extractor.tsconfig.json -> compilerOptions.paths["react-icons"]
+ */
+export {}

theatre/studio/src/TheatreStudio.ts

@@ -35,8 +35,8 @@ export interface ITransactionAPI {
    *   set(obj.props.z, 10)
    * })
    * ```
-   * @param pointer A Pointer, like object.props
-   * @param value The value to override the existing value. This is treated as a deep partial value.
+   * @param pointer - A Pointer, like object.props
+   * @param value - The value to override the existing value. This is treated as a deep partial value.
    */
   set<V>(pointer: Pointer<V>, value: V): void
   /**
@@ -152,14 +152,14 @@ export interface IStudio {
     /**
      * The local storage key to use to persist the state.
      *
-     * @default "theatrejs:0.4"
+     * Default: "theatrejs:0.4"
      */
     persistenceKey?: string
     /**
      * Whether to persist the changes in the browser's temporary storage.
      * It is useful to set this to false in the test environment or when debugging things.
      *
-     * @default true
+     * Default: true
      */
     usePersistentStorage?: boolean
   }): void
@@ -212,7 +212,7 @@ export interface IStudio {
    * automatically runs scrub.commit() after `threshhold` milliseconds have
    * passed after the last `scrub.capture`.
    *
-   * @param threshhold How long to wait before committing the scrub
+   * @param threshhold - How long to wait before committing the scrub
    *
    * Usage:
    * ```ts
@@ -288,7 +288,7 @@ export interface IStudio {
   /**
    * Creates a new pane
    *
-   * @param paneClass The class name of the pane (provided by an extension)
+   * @param paneClass - The class name of the pane (provided by an extension)
    */
   createPane<PaneClass extends string>(
     paneClass: PaneClass,
@@ -307,7 +307,7 @@ export interface IStudio {
    * to programmatically save the state of your projects to the storage system of your
    * choice, rather than manually clicking on the "Export" button in the UI.
    *
-   * @param projectId same projectId as in `core.getProject(projectId)`
+   * @param projectId - same projectId as in `core.getProject(projectId)`
    *
    * Usage:
    * ```ts