@arcgis/api-extractor 5.0.0-next.7 → 5.0.0-next.70

package/dist/apiJson.d.ts

@@ -4,8 +4,11 @@
  * `api.json` is a superset of custom-elements-manifest.
  *
  * @see https://custom-elements-manifest.open-wc.org/analyzer/getting-started/
+ * @privateRemarks
+ * PERF: when most code is moved from jsapi-extractor into api-extractor, replace
+ * ? with |undefined here to ensure more consistent shape.
  */
-export type ApiJson = {
+export interface ApiJson {
     /**
      * The timestamp at which the metadata was generated, in the format
      * `YYYY-MM-DDThh:mm:ss`.
@@ -20,26 +23,7 @@ export type ApiJson = {
      * @remarks
      * Not present in vanilla custom-elements-manifest.
      */
-    compiler: {
-        /**
-         * The name of the compiler that generated the metadata.
-         *
-         * @example "@arcgis/api-extractor"
-         */
-        name: string;
-        /**
-         * The version of the compiler that generated the metadata.
-         *
-         * @example "4.32.0"
-         */
-        version: string;
-        /**
-         * The version of TypeScript that was used to generate the metadata.
-         *
-         * @example "5.4.5"
-         */
-        typescriptVersion: string;
-    };
+    compiler: ApiJsonCompiler;
     /**
      * The version of the schema used in this file.
      *
@@ -53,7 +37,7 @@ export type ApiJson = {
      * contains information irrelevant to custom element catalogs and
      * documentation viewers.
      *
-     * @remarks
+     * @deprecated
      * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
      * with custom-elements-manifest.
      */
@@ -71,33 +55,51 @@ export type ApiJson = {
      *
      * @default false
      *
-     * @remarks
+     * @deprecated
      * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
      * with custom-elements-manifest.
      */
-    deprecated?: boolean | string;
-};
+    deprecated?: string | true;
+}
+export interface ApiJsonCompiler {
+    /**
+     * The name of the compiler that generated the metadata.
+     *
+     * @example "@arcgis/api-extractor"
+     */
+    name: string;
+    /**
+     * The version of the compiler that generated the metadata.
+     *
+     * @example "4.32.0"
+     */
+    version: string;
+    /**
+     * The version of TypeScript that was used to generate the metadata.
+     *
+     * @example "5.4.5"
+     */
+    typescriptVersion: string;
+}
 export type ApiModule = ApiJavaScriptModule;
-export type ApiJavaScriptModule = {
+export interface ApiJavaScriptModule extends ApiWithDescription, ApiWithDocsTags, ApiWithUnusedSummary {
     kind: "javascript-module";
     /**
-     * Path to the javascript file needed to be imported.
+     * Public import path for the module
      *
-     * @example "src/components/property-types/property-types.tsx"
+     * @example "components/arcgis-map"
      */
     path: string;
     /**
-     * A markdown summary suitable for display in a listing.
+     * The original source file path, relative to extraction root (most commonly
+     * src/ folder).
+     *
+     * @example "components/map/map.tsx"
      *
      * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    summary?: string;
-    /**
-     * A markdown description of the module.
+     * Not present in vanilla custom-elements-manifest.
      */
-    description?: string;
+    sourcePath: string;
     /**
      * The declarations of a module.
      *
@@ -115,17 +117,67 @@ export type ApiJavaScriptModule = {
      * Whether the module is deprecated.
      * If the value is a string, it's the reason for the deprecation.
      *
+     * @remarks
+     * If module is marked as deprecated, all its declarations should also be
+     * marked as deprecated. This is because in TypeScript, a usage of a
+     * declaration will only be marked as deprecated if the declaration itself
+     * is marked as deprecated, rather than its module.
+     *
      * @default false
      */
-    deprecated?: boolean | string;
-};
-export type ApiExport = ApiCustomElementExport | ApiJavaScriptExport;
+    deprecated?: string | true;
+}
+export interface ApiWithDescription {
+    /**
+     * A markdown description of an api node
+     */
+    description?: string;
+}
+export interface ApiWithDocsTags {
+    docsTags?: ApiDocsTag[];
+}
+export interface ApiWithDeprecated {
+    /**
+     * Whether the node is deprecated.
+     * If the value is a string, it's the reason for the deprecation.
+     *
+     * @default false
+     */
+    deprecated?: string | true;
+}
+export interface ApiWithUnusedSummary {
+    /**
+     * A markdown summary suitable for display in a listing.
+     *
+     * @deprecated
+     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
+     * with custom-elements-manifest.
+     */
+    summary?: string;
+}
 /**
+ * A descriptor for a single JSDoc tag found in a block comment.
+ *
  * @remarks
- * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
- * with custom-elements-manifest.
+ * Some tags have dedicated fields. Those will be excluded from array of
+ * "docsTags".
  */
-export type ApiJavaScriptExport = {
+export interface ApiDocsTag {
+    /**
+     * The tag name (immediately following the '@').
+     *
+     * @example "since"
+     */
+    name: string;
+    /**
+     * The description that immediately follows the tag name.
+     *
+     * @example "4.31"
+     */
+    text?: string;
+}
+export type ApiExport = ApiCustomElementExport | ApiJavaScriptExport | ApiTypeScriptExport;
+export interface ApiJavaScriptExport {
     kind: "js";
     /**
      * The name of the exported symbol.
@@ -151,9 +203,23 @@ export type ApiJavaScriptExport = {
      * If the value is a string, it's the reason for the deprecation.
      *
      * @default false
+     * @deprecated
+     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
+     * with custom-elements-manifest. Read the deprecated status from the declaration.
      */
-    deprecated?: boolean | string;
-};
+    deprecated?: string | true;
+}
+/**
+ * Indicates that the export is type-only and has no runtime impact (is a type alias
+ * or an interface).
+ *
+ * @remarks
+ * Not present in vanilla custom-elements-manifest, but may be added in the future.
+ * See https://github.com/webcomponents/custom-elements-manifest/pull/77#issuecomment-873552677
+ */
+export interface ApiTypeScriptExport extends Omit<ApiJavaScriptExport, "kind"> {
+    kind: "ts";
+}
 /**
  * A global custom element definition, ie the result of a
  * `customElements.define()` call.
@@ -161,7 +227,7 @@ export type ApiJavaScriptExport = {
  * This is represented as an export because a definition makes the element
  * available outside of the module it's defined it.
  */
-export type ApiCustomElementExport = {
+export interface ApiCustomElementExport {
     kind: "custom-element-definition";
     /**
      * The tag name of the custom element.
@@ -180,13 +246,13 @@ export type ApiCustomElementExport = {
      * If the value is a string, it's the reason for the deprecation.
      *
      * @default false
-     * @remarks
+     * @deprecated
      * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
+     * with custom-elements-manifest. Read the deprecated status from the declaration.
      */
-    deprecated?: boolean | string;
-};
-export type ApiDeclaration = ApiClassDeclaration | ApiCustomElementDeclaration | ApiCustomElementMixinDeclaration | ApiFunctionDeclaration | ApiMixinDeclaration | ApiVariableDeclaration;
+    deprecated?: string | true;
+}
+export type ApiDeclaration = ApiClassDeclaration | ApiCustomElementDeclaration | ApiCustomElementMixinDeclaration | ApiFunctionDeclaration | ApiInterfaceDeclaration | ApiMixinDeclaration | ApiVariableDeclaration;
 /**
  * A reference to an export of a module.
  *
@@ -200,7 +266,7 @@ export type ApiDeclaration = ApiClassDeclaration | ApiCustomElementDeclaration |
  * References to global symbols like `Array`, `HTMLElement`, or `Event` should
  * use a `package` name of `"global:"`.
  */
-export type ApiReference = {
+export interface ApiReference {
     /**
      * @example "AreaMeasurementAnalysis"
      */
@@ -219,23 +285,15 @@ export type ApiReference = {
      * @example "https://developers.arcgis.com/javascript/latest/api-reference/esri-views-MapView.html"
      */
     viewUrl?: string;
-};
+}
 /**
- * A reference to the source of a declaration or member.
- *
  * @remarks
- * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
- * with custom-elements-manifest.
+ * Not present in vanilla custom-elements-manifest.
  */
-export type ApiSourceReference = {
-    /**
-     * An absolute URL to the source (ie. a GitHub URL).
-     */
-    href: string;
-};
+export interface ApiReferenceWithTypeArguments extends ApiReference {
+    typeArguments?: ApiType[];
+}
 /**
- * A description of a custom element class.
- *
  * Custom elements are JavaScript classes, so this extends from
  * `ClassDeclaration` and adds custom-element-specific features like attributes,
  * events, and slots.
@@ -252,7 +310,7 @@ export type ApiSourceReference = {
  * these cases one `Module` should contain the `CustomElement` without a
  * tagName, and another `Module` should contain the `CustomElementExport`.
  */
-export type ApiCustomElementDeclaration = Omit<ApiClassDeclaration, "members"> & {
+export interface ApiCustomElementDeclaration extends ApiClassDeclaration, ApiWithPrivacy {
     /**
      * An optional tag name that should be specified if this is a
      * self-registering element.
@@ -274,7 +332,6 @@ export type ApiCustomElementDeclaration = Omit<ApiClassDeclaration, "members"> &
      */
     pascalCaseName: string;
     members: ApiCustomElementMember[];
-    superclass: ApiReference;
     /**
      * The attributes that this element is known to understand.
      *
@@ -283,10 +340,6 @@ export type ApiCustomElementDeclaration = Omit<ApiClassDeclaration, "members"> &
      * "attributes" is not necessary.
      */
     attributes?: ApiAttribute[];
-    /**
-     * The events that this element fires.
-     */
-    events?: ApiEvent[];
     /**
      * The shadow dom content slots that this element accepts.
      */
@@ -300,71 +353,47 @@ export type ApiCustomElementDeclaration = Omit<ApiClassDeclaration, "members"> &
      */
     customElement: true;
     /**
+     * @default "shadow"
+     *
      * @remarks
      * Not present in vanilla custom-elements-manifest.
      */
-    docsTags?: ApiDocsTag[];
+    encapsulation?: "none" | "shadow";
     /**
      * The path from which the component can be imported.
      *
+     * @deprecated Use ApiModule.path instead.
+     *
      * @example "components/arcgis-area-measurement-2d"
      *
      * @remarks
      * Not present in vanilla custom-elements-manifest.
      */
     importPath: string;
+}
+export interface ApiWithPrivacy {
     /**
-     * @default "shadow"
-     *
-     * @remarks
-     * Not present in vanilla custom-elements-manifest.
-     */
-    encapsulation?: "none" | "shadow";
-};
-/**
- * A descriptor for a single JSDoc tag found in a block comment.
- *
- * @remarks
- * Some tags have dedicated fields. Those will be excluded from array of
- * "docsTags".
- */
-export type ApiDocsTag = {
-    /**
-     * The tag name (immediately following the '@').
+     * @default "public"
      *
-     * @example "since"
-     */
-    name: string;
-    /**
-     * The description that immediately follows the tag name.
+     * If this field is absent, default value is assumed.
+     * All private fields are excluded from the api.json.
+     * So in practice, this value will be either "protected" or undefined.
      *
-     * @example "4.31"
+     * \@arcgis/api-extractor may only ever set this field on class members, even
+     * though the original spec also allows it on classes and events.
      */
-    text?: string;
-};
+    privacy?: "private" | "protected" | "public";
+}
 /**
- * For most use cases, the "members" array includes properties will all the
+ * For most use cases, the "members" array includes properties with all the
  * information included in the "attributes" array. Thus directly accessing
  * "attributes" is not necessary.
  */
-export type ApiAttribute = {
+export interface ApiAttribute extends ApiWithDeprecated, ApiWithDescription, ApiWithInheritance, ApiWithUnusedSummary {
     /**
      * @example "initial-count"
      */
     name: string;
-    /**
-     * A markdown summary suitable for display in a listing.
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    summary?: string;
-    /**
-     * A markdown description.
-     */
-    description?: string;
-    inheritedFrom?: ApiReference;
     /**
      * The type that the attribute will be serialized/deserialized as.
      */
@@ -384,151 +413,95 @@ export type ApiAttribute = {
      * @example "initialCount"
      */
     fieldName?: string;
-    /**
-     * Whether the attribute is deprecated.
-     * If the value is a string, it's the reason for the deprecation.
-     *
-     * @default false
-     */
-    deprecated?: boolean | string;
-};
-export type ApiEvent = {
+}
+export interface ApiEvent extends ApiWithDescription, ApiWithDocsTags, ApiWithDeprecated, ApiWithInheritance, ApiWithPrivacy, ApiWithUnusedSummary {
     /**
      * @example "arcgisClick"
      */
     name: string;
-    /**
-     * A markdown summary suitable for display in a listing.
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    summary?: string;
-    /**
-     * A markdown description.
-     */
-    description?: string;
     /**
      * The type of the event object that's fired.
      */
     type: ApiType;
-    inheritedFrom?: ApiReference;
-    /**
-     * Whether the event is deprecated.
-     * If the value is a string, it's the reason for the deprecation.
-     *
-     * @default false
-     */
-    deprecated?: boolean | string;
-    /**
-     * @remarks
-     * Not present in vanilla custom-elements-manifest.
-     */
-    docsTags?: ApiDocsTag[];
     /**
      * @default true
      *
      * @remarks
      * Not present in vanilla custom-elements-manifest.
      */
-    bubbles?: boolean;
+    bubbles?: false;
     /**
      * @default true
      *
      * @remarks
      * Not present in vanilla custom-elements-manifest.
      */
-    cancelable?: boolean;
+    cancelable?: false;
     /**
      * @default true
      *
      * @remarks
      * Not present in vanilla custom-elements-manifest.
      */
-    composed?: boolean;
+    composed?: false;
+}
+export interface ApiWithInheritance {
     /**
-     * @default "public"
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Present for completeness.
+     * To keep api.json size in check, `inheritedFrom` object does not include
+     * `viewUrl`.
      */
-    privacy?: ApiPrivacy;
-};
+    inheritedFrom?: ApiReference;
+}
 /**
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot
  */
-export type ApiSlot = {
+export interface ApiSlot extends ApiWithDescription, ApiWithUnusedSummary {
     /**
      * The slot name, or the empty string for an unnamed slot.
      *
      * @example "header"
      */
     name: string;
-    /**
-     * A markdown summary suitable for display in a listing.
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    summary?: string;
-    /**
-     * A markdown description.
-     */
-    description?: string;
     /**
      * Whether the slot is deprecated.
      * If the value is a string, it's the reason for the deprecation.
      *
      * @default false
      *
-     * @remarks
+     * @deprecated
      * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
      * with custom-elements-manifest.
      */
-    deprecated?: boolean | string;
-};
+    deprecated?: string | true;
+}
 /**
  * The description of exposed CSS Parts
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_shadow_parts
  */
-export type ApiCssPart = {
+export interface ApiCssPart extends ApiWithDescription, ApiWithUnusedSummary {
     /**
      * @example "tab"
      */
     name: string;
-    /**
-     * A markdown summary suitable for display in a listing.
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    summary?: string;
-    /**
-     * A markdown description.
-     */
-    description?: string;
     /**
      * Whether the CSS shadow part is deprecated.
      * If the value is a string, it's the reason for the deprecation.
      *
      * @default false
      *
-     * @remarks
+     * @deprecated
      * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
      * with custom-elements-manifest.
      */
-    deprecated?: boolean | string;
-};
+    deprecated?: string | true;
+}
 /**
  * The description of a CSS Custom State.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
  */
-export type ApiCssCustomState = {
+export interface ApiCssCustomState extends ApiWithDescription, ApiWithUnusedSummary {
     /**
      * The name of the state. Note: Unlike CSS custom properties, custom states
      * do not have a leading `--`.
@@ -536,31 +509,19 @@ export type ApiCssCustomState = {
      * @example "active"
      */
     name: string;
-    /**
-     * A markdown summary suitable for display in a listing.
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    summary?: string;
-    /**
-     * A markdown description.
-     */
-    description?: string;
     /**
      * Whether the CSS custom state is deprecated.
      * If the value is a string, it's the reason for the deprecation.
      *
      * @default false
      *
-     * @remarks
+     * @deprecated
      * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
      * with custom-elements-manifest.
      */
-    deprecated?: boolean | string;
-};
-export type ApiCssCustomProperty = {
+    deprecated?: string | true;
+}
+export interface ApiCssCustomProperty extends ApiWithDescription, ApiWithUnusedSummary {
     /**
      * The name of the property, including leading `--`.
      *
@@ -580,34 +541,26 @@ export type ApiCssCustomProperty = {
      * "<length> | <percentage>": accepts lengths or percentages but not calc expressions with a combination of the two
      * "small | medium | large": accepts one of these values set as custom indents.
      * "*": any valid token
-     */
-    syntax?: string;
-    default?: string;
-    /**
-     * A markdown summary suitable for display in a listing.
      *
-     * @remarks
+     * @deprecated
      * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
      * with custom-elements-manifest.
      */
-    summary?: string;
-    /**
-     * A markdown description.
-     */
-    description?: string;
+    syntax?: string;
+    default?: string;
     /**
      * Whether the CSS custom property is deprecated.
      * If the value is a string, it's the reason for the deprecation.
      *
      * @default false
      *
-     * @remarks
+     * @deprecated
      * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
      * with custom-elements-manifest.
      */
-    deprecated?: boolean | string;
-};
-export type ApiType = {
+    deprecated?: string | true;
+}
+export interface ApiType extends ApiWithUnusedSource {
     /**
      * The full string representation of the type, in whatever type syntax is
      * used, such as JSDoc, Closure, or TypeScript.
@@ -628,21 +581,52 @@ export type ApiType = {
      * and `BarElement` without understanding arrays, generics, or union types.
      */
     references?: ApiTypeReference[];
-    /**
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    source?: ApiSourceReference;
     /**
      * An enum of possible values for this type.
      *
      * @remarks
      * Not present in vanilla custom-elements-manifest.
+     *
+     * @privateRemarks
+     * FINAL: should we drop this field in favor of offering a util that infers
+     * type values from the type string?
+     *
+     * Pros:
+     * - smaller api.json
+     * - simpler implementation in some ways (don't need to keep type string and
+     *   values in sync when doing post processing)
+     * - one less non-standard field
+     *
+     * Cons:
+     * - Lumina compiler at present relies on type values in several places, so
+     *   it may have to compute this anyway
+     * - inferring it from the type string is not trivial, think of:
+     *
+     *   ```ts
+     *   type A = "a|\"" | { b: string | undefined } | T extends `a${1|2}b` ? X | Y : Z;
+     *   ```
+     *
+     *   though, ChatGPT one-shotted a working solution:
+     *   https://chatgpt.com/share/68ccd574-2a8c-8003-a6cc-aa3ef01c40ad
+     *
+     *   still, it will be a maintenance burden whenever new TS syntax is added
      */
     values?: ApiValue[];
-};
-export type ApiValue = {
+}
+export interface ApiWithUnusedSource {
+    /**
+     * A reference to the source of a declaration or member.
+     * An absolute URL to the source (ie. a GitHub URL).
+     *
+     * @deprecated
+     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
+     * with custom-elements-manifest.
+     */
+    source?: {
+        href: string;
+    };
+}
+export interface ApiValue {
     /**
      * @example "string"
      */
@@ -651,7 +635,7 @@ export type ApiValue = {
      * @example "active"
      */
     value?: string;
-};
+}
 /**
  * A reference that is associated with a type string and optionally a range
  * within the string.
@@ -661,31 +645,40 @@ export type ApiValue = {
  * type string is the symbol referenced and the name should match the type
  * string.
  */
-export type ApiTypeReference = ApiReference & {
+export interface ApiTypeReference extends ApiReference {
     start?: number;
     end?: number;
-};
-/**
- * The common interface of classes and mixins.
- */
-export type ApiClassDeclaration = {
-    kind: "class";
+}
+export interface ApiObjectLikeDeclaration extends ApiWithDescription, ApiWithDocsTags, ApiWithDeprecated, ApiWithUnusedSource, ApiWithUnusedSummary, ApiWithTypeParameters {
     /**
      * @example "ArcgisCounter"
      */
     name: string;
-    /**
-     * A markdown summary suitable for display in a listing.
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    summary?: string;
-    /**
-     * A markdown description of the class.
-     */
-    description?: string;
+    members?: ApiClassMember[];
+}
+export interface ApiWithTypeParameters {
+    typeParameters?: ApiTypeParameter[];
+}
+/**
+ * @remarks
+ * Not present in vanilla custom-elements-manifest.
+ */
+export interface ApiTypeParameter {
+    name: string;
+    constraint?: ApiType;
+    default?: ApiType;
+    /** @default false */
+    const?: true;
+    /** @default false */
+    in?: true;
+    /** @default false */
+    out?: true;
+}
+/**
+ * The common interface of classes and mixins.
+ */
+export interface ApiClassDeclaration extends ApiObjectLikeDeclaration, ApiWithEvents {
+    kind: "class";
     /**
      * The superclass of this class.
      *
@@ -693,7 +686,7 @@ export type ApiClassDeclaration = {
      * includes the mixin applications and the true superclass is computed
      * from them.
      */
-    superclass?: ApiReference;
+    superclass?: ApiReferenceWithTypeArguments;
     /**
      * Any class mixins applied in the extends clause of this class.
      *
@@ -706,133 +699,92 @@ export type ApiClassDeclaration = {
      * matches the order of language used to describe mixin application, like
      * "S with A, B".
      *
-     * @example
-     *
-     * ```javascript
-     * class T extends B(A(S)) {}
-     * ```
-     *
-     * is described by:
-     * ```json
-     * {
-     *   "kind": "class",
-     *   "superclass": {
-     *     "name": "S"
-     *   },
-     *   "mixins": [
-     *     {
-     *       "name": "A"
-     *     },
-     *     {
-     *       "name": "B"
-     *     },
-     *   ]
-     * }
-     * ```
+     * @see https://webgis.esri.com/webgis/core/core/mixins
      *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
      */
-    mixins?: ApiReference[];
-    members?: ApiClassMember[];
+    mixins?: ApiReferenceWithTypeArguments[];
+}
+export interface ApiWithEvents {
     /**
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
+     * The events that this object fires.
      */
-    source?: ApiSourceReference;
+    events?: ApiEvent[];
+}
+/**
+ * An interface that describes the properties and methods of an object.
+ *
+ * @remarks
+ * Not yet part of vanilla custom-elements-manifest, but may be added in the
+ * future. See https://github.com/webcomponents/custom-elements-manifest/pull/77
+ */
+export interface ApiInterfaceDeclaration extends ApiObjectLikeDeclaration {
+    kind: "interface";
     /**
-     * Whether the class or mixin is deprecated.
-     * If the value is a string, it's the reason for the deprecation.
-     *
-     * @default false
+     * The interfaces that this interface extends.
      */
-    deprecated?: boolean | string;
+    supertypes?: ApiReferenceWithTypeArguments[];
     /**
-     * @default "public"
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Present for completeness.
+     * Present in type aliases only. If type alias is an intersection, then type
+     * reference members will be represented in the `supertypes` field. If type
+     * alias is an object literal, then object members will be represented in
+     * the `members` field. Thus, the `type` field will only be used for unions,
+     * mapped types, conditional types, and other types that cannot be represented
+     * as supertypes/members.
      */
-    privacy?: ApiPrivacy;
-};
-export type ApiClassMember = ApiClassField | ApiClassMethod;
+    type?: ApiType;
+}
+export type ApiClassMember = ApiClassCallSignature | ApiClassConstructor | ApiClassField | ApiClassMethod;
 export type ApiCustomElementMember = ApiClassMethod | ApiCustomElementField;
 /**
  * The common interface of variables, class fields, and function
  * parameters.
  */
-export type ApiPropertyLike = {
+export interface ApiPropertyLike extends ApiWithDescription, ApiWithDocsTags, ApiWithDeprecated, ApiWithUnusedSummary {
     /**
      * @example "initialCount"
+     * @example Special names appear unquoted and unescaped: "@eventTypes"
+     * @example Computed Symbol properties appear as "[Symbol.iterator]"
      */
     name: string;
-    /**
-     * A markdown summary suitable for display in a listing.
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    summary?: string;
-    /**
-     * A markdown description of the field.
-     */
-    description?: string;
     type: ApiType;
     /**
      * @example 10
      */
     default?: string;
-    /**
-     * Whether the property is deprecated.
-     * If the value is a string, it's the reason for the deprecation.
-     *
-     * @default false
-     */
-    deprecated?: boolean | string;
+}
+export interface ApiClassField extends ApiPropertyLike, ApiWithInheritance, ApiWithStatic, ApiWithPrivacy, ApiWithUnusedSource {
+    kind: "field";
     /**
      * Whether the property is read-only.
      *
      * @default false
      */
-    readonly?: boolean;
-};
-export type ApiClassField = ApiPropertyLike & {
-    kind: "field";
+    readonly?: true;
     /**
-     * @default false
+     * Getter type if any.
      *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
+     * This property will only be set if it differs from `type` property in order
+     * to keep documentation UI cleaner, and api.json smaller.
      *
-     * All static members are excluded from the api.json.
-     */
-    static?: boolean;
-    /**
-     * @default "public"
+     * If property is read-only, only the `type` property will be set.
      *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
+     * @default undefined
      *
-     * All private and protected fields are excluded from the api.json.
+     * @remarks
+     * Not present in vanilla custom-elements-manifest.
      */
-    privacy?: ApiPrivacy;
-    inheritedFrom?: ApiReference;
+    getterType?: ApiType;
+}
+export interface ApiWithStatic {
     /**
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
+     * @default false
      */
-    source?: ApiSourceReference;
-};
+    static?: true;
+}
 /**
  * Additional metadata for fields on custom elements.
  */
-export type ApiCustomElementField = ApiClassField & {
+export interface ApiCustomElementField extends ApiClassField {
     /**
      * The corresponding attribute name if there is one.
      *
@@ -849,22 +801,7 @@ export type ApiCustomElementField = ApiClassField & {
      *
      * @default false
      */
-    reflects?: boolean;
-    /**
-     * @remarks
-     * Not present in vanilla custom-elements-manifest.
-     */
-    docsTags?: ApiDocsTag[];
-    /**
-     * If getter type differs from setter type, this property will
-     * contain the getter type.
-     *
-     * @default undefined
-     *
-     * @remarks
-     * Not present in vanilla custom-elements-manifest.
-     */
-    getterType?: Pick<ApiType, "text">;
+    reflects?: true;
     /**
      * For some properties, we show them as read-only in the docs and in the
      * typings but don't actually enforce read-only at runtime.
@@ -879,214 +816,109 @@ export type ApiCustomElementField = ApiClassField & {
      * @remarks
      * Not present in vanilla custom-elements-manifest.
      */
-    docsOnlyReadonly?: boolean;
-};
-export type ApiClassMethod = ApiFunctionLike & {
+    docsOnlyReadonly?: true;
+}
+export interface ApiClassMethod extends ApiFunctionLike, ApiWithInheritance, ApiWithStatic, ApiWithPrivacy, ApiWithUnusedSource {
     kind: "method";
     /**
      * @default false
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     *
-     * All static members are excluded from the api.json.
-     */
-    static?: boolean;
-    /**
-     * @default "public"
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     *
-     * All private and protected fields are excluded from the api.json.
      */
-    privacy?: ApiPrivacy;
-    inheritedFrom?: ApiReference;
-    /**
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    source?: ApiSourceReference;
-    /**
-     * @remarks
-     * Not present in vanilla custom-elements-manifest.
-     */
-    docsTags?: ApiDocsTag[];
+    static?: true;
     /**
+     * @example "(options?: __esri.PopupViewOpenPopupOptions): Promise<void>"
+     * @deprecated
+     * If documentation UI shows a table with parameters and the return type, then
+     * displaying the signature is redundant.
+     * Still, if needed, you can use printSignature() util from
+     * `@arcgis/api-extractor`.
      * @remarks
      * Not present in vanilla custom-elements-manifest.
      */
     signature: string;
-    /**
-     * @default false
-     *
-     * @remarks
-     * Not present in vanilla custom-elements-manifest.
-     */
-    async?: boolean;
-};
+}
 /**
- * A description of a class mixin.
- *
- * Mixins are functions which generate a new subclass of a given superclass.
- * This interfaces describes the class and custom element features that
- * are added by the mixin. As such, it extends the CustomElement interface and
- * ClassLike interface.
- *
- * Since mixins are functions, it also extends the FunctionLike interface. This
- * means a mixin is callable, and has parameters and a return type.
- *
- * The return type is often hard or impossible to accurately describe in type
- * systems like TypeScript. It requires generics and an `extends` operator
- * that TypeScript lacks. Therefore it's recommended that the return type is
- * left empty. The most common form of a mixin function takes a single
- * argument, so consumers of this interface should assume that the return type
- * is the single argument subclassed by this declaration.
- *
- * A mixin should not have a superclass. If a mixins composes other mixins,
- * they should be listed in the `mixins` field.
- *
- * See more information on the class mixin pattern in JavaScript:
- * https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/
- *
- * @example
- *
- * This JavaScript mixin declaration:
- * ```javascript
- * const MyMixin = (base) => class extends base {
- *   foo() { ... }
- * }
- * ```
- *
- * Is described by this JSON:
- * ```json
- * {
- *   "kind": "mixin",
- *   "name": "MyMixin",
- *   "parameters": [
- *     {
- *       "name": "base",
- *     }
- *   ],
- *   "members": [
- *     {
- *       "kind": "method",
- *       "name": "foo",
- *     }
- *   ]
- * }
- * ```
- *
  * @remarks
- * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
- * with custom-elements-manifest.
+ * Not present in vanilla custom-elements-manifest.
  */
-export type ApiMixinDeclaration = ApiClassDeclaration & ApiFunctionLike & {
-    kind: "mixin";
-};
+export interface ApiClassConstructor extends Omit<ApiFunctionLike, "name" | "return">, ApiWithInheritance, ApiWithPrivacy {
+    kind: "constructor";
+}
 /**
- * A class mixin that also adds custom element related properties.
- *
  * @remarks
- * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
- * with custom-elements-manifest.
+ * Not present in vanilla custom-elements-manifest.
  */
-export type ApiCustomElementMixinDeclaration = ApiCustomElementDeclaration & ApiMixinDeclaration;
+export interface ApiClassCallSignature extends Omit<ApiFunctionLike, "name">, ApiWithInheritance, ApiWithPrivacy {
+    kind: "call-signature";
+}
 /**
- * @remarks
- * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
- * with custom-elements-manifest.
+ * A description of a class mixin.
+ *
+ * @see https://webgis.esri.com/webgis/core/core/mixins
  */
-export type ApiVariableDeclaration = ApiPropertyLike & {
-    kind: "variable";
-    source?: ApiSourceReference;
-};
+export interface ApiMixinDeclaration extends Omit<ApiFunctionLike, "return">, ApiObjectLikeDeclaration, ApiWithEvents {
+    kind: "mixin";
+    /**
+     * The mixins that this mixin uses, if any.
+     */
+    mixins?: ApiReferenceWithTypeArguments[];
+    /**
+     * @deprecated
+     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
+     * with custom-elements-manifest.
+     */
+    return?: ApiFunctionLikeReturn;
+}
 /**
- * @remarks
+ * A class mixin that also adds custom element related properties.
+ *
+ * @deprecated
  * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
  * with custom-elements-manifest.
  */
-export type ApiFunctionDeclaration = ApiFunctionLike & {
+export interface ApiCustomElementMixinDeclaration extends Omit<ApiCustomElementDeclaration, "kind">, Omit<ApiMixinDeclaration, "members"> {
+}
+export interface ApiVariableDeclaration extends ApiPropertyLike, ApiWithUnusedSource {
+    kind: "variable";
+}
+export interface ApiFunctionDeclaration extends ApiFunctionLike, ApiWithUnusedSource {
     kind: "function";
-    source?: ApiSourceReference;
-};
-export type ApiParameter = ApiPropertyLike & {
+}
+export interface ApiParameter extends ApiPropertyLike {
     /**
      * Whether the parameter is optional.
      *
      * @default false
      */
-    optional?: boolean;
+    optional?: true;
     /**
      * @default false
      *
      * Whether the parameter is a rest parameter. Only the last parameter may be a rest parameter.
      * Undefined implies single parameter.
      */
-    rest?: boolean;
-};
-export type ApiFunctionLike = {
+    rest?: true;
+}
+export interface ApiFunctionLike extends ApiWithDescription, ApiWithDocsTags, ApiWithDeprecated, ApiWithUnusedSummary, ApiWithTypeParameters {
     /**
      * @example "increment"
+     * @example Special names appear unquoted and unescaped: "@eventTypes"
+     * @example Computed Symbol properties appear as "[Symbol.iterator]"
      */
     name: string;
-    /**
-     * A markdown summary suitable for display in a listing.
-     *
-     * @remarks
-     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-     * with custom-elements-manifest.
-     */
-    summary?: string;
-    /**
-     * A markdown description.
-     */
-    description?: string;
-    /**
-     * Whether the function is deprecated.
-     * If the value is a string, it's the reason for the deprecation.
-     *
-     * @default false
-     */
-    deprecated?: boolean | string;
     /**
      * @default []
      */
     parameters?: ApiParameter[];
-    return?: {
-        type?: ApiType;
-        /**
-         * A markdown summary suitable for display in a listing.
-         *
-         * @remarks
-         * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
-         * with custom-elements-manifest.
-         */
-        summary?: string;
-        /**
-         * A markdown description.
-         */
-        description?: string;
-    };
-};
-/**
- * @remarks
- * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
- * with custom-elements-manifest.
- */
-export type ApiPrivacy = "private" | "protected" | "public";
-export type ApiDemo = {
-    /**
-     * A markdown description of the demo.
-     */
-    description: string;
+    return: ApiFunctionLikeReturn;
+}
+export interface ApiFunctionLikeReturn extends ApiWithDescription, ApiWithUnusedSummary {
+    type: ApiType;
+}
+export interface ApiDemo extends ApiWithUnusedSource {
     /**
      * Relative URL of the demo if it's published with the package. Absolute URL
      * if it's hosted.
      */
     url: string;
-    source?: ApiSourceReference;
-};
+    description: NonNullable<ApiWithDescription["description"]>;
+}