@ui5/webcomponents-tools 1.22.0-rc.1 → 1.22.0-rc.2

package/lib/cem/types.d.ts

@@ -1,4 +1,12 @@
-export type Privacy = "private" | "protected" | "public"
+/**
+ * @license
+ * Copyright (c) 2019 The Polymer Project Authors. All rights reserved.
+ * This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
+ * The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
+ * The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
+ * Code distributed by Google as part of the polymer project is also
+ * subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
+ */
 
 /**
  * The top-level interface of a custom elements manifest file.
@@ -15,14 +23,10 @@ export type Privacy = "private" | "protected" | "public"
  */
 export interface Package {
   /**
-   * Whether the package is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
-   */
-  deprecated?: string | boolean
-  /**
-   * An array of the modules this package contains.
+   * The version of the schema used in this file.
    */
-  modules: JavaScriptModule[]
+  schemaVersion: string;
+
   /**
    * The Markdown to use for the main readme of this package.
    *
@@ -30,131 +34,135 @@ export interface Package {
    * file contains information irrelevant to custom element catalogs and
    * documentation viewers.
    */
-  readme?: string
+  readme?: string;
+
   /**
-   * The version of the schema used in this file.
+   * An array of the modules this package contains.
+   */
+  modules: Array<Module>;
+
+  /**
+   * Whether the package is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
    */
-  schemaVersion: string
+  deprecated?: boolean | string;
 }
+
+// This type may expand in the future to include JSON, CSS, or HTML
+// modules.
+export type Module = JavaScriptModule;
+
 export interface JavaScriptModule {
+  kind: 'javascript-module';
+
   /**
-   * The declarations of a module.
-   *
-   * For documentation purposes, all declarations that are reachable from
-   * exports should be described here. Ie, functions and objects that may be
-   * properties of exported objects, or passed as arguments to functions.
+   * Path to the javascript file needed to be imported. 
+   * (not the path for example to a typescript file.)
    */
-  declarations?: (
-    | ClassDeclaration
-    | FunctionDeclaration
-    | MixinDeclaration
-    | VariableDeclaration
-    | CustomElementDeclaration
-    | CustomElementMixinDeclaration
-  )[]
+  path: string;
+
   /**
-   * Whether the module is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
+   * A markdown summary suitable for display in a listing.
    */
-  deprecated?: string | boolean
+  summary?: string;
+
   /**
    * A markdown description of the module.
    */
-  description?: string
-  /**
-   * The exports of a module. This includes JavaScript exports and
-   * custom element definitions.
-   */
-  exports?: (JavaScriptExport | CustomElementExport)[]
-  kind: "javascript-module"
+  description?: string;
+
   /**
-   * Path to the javascript file needed to be imported.
-   * (not the path for example to a typescript file.)
+   * The declarations of a module.
+   *
+   * For documentation purposes, all declarations that are reachable from
+   * exports should be described here. Ie, functions and objects that may be
+   * properties of exported objects, or passed as arguments to functions.
    */
-  path: string
+  declarations?: Array<Declaration>;
+
   /**
-   * A markdown summary suitable for display in a listing.
+   * The exports of a module. This includes JavaScript exports and
+   * custom element definitions.
    */
-  summary?: string
-}
-export interface ClassDeclaration {
+  exports?: Array<Export>;
+
   /**
-   * Whether the class or mixin is deprecated.
+   * Whether the module is deprecated.
    * If the value is a string, it's the reason for the deprecation.
    */
-  deprecated?: string | boolean
-  /**
-   * A markdown description of the class.
-   */
-  description?: string
-  kind: "class"
-  members?: (ClassField | ClassMethod)[]
+  deprecated?: boolean | string;
+}
+
+export type Export = JavaScriptExport | CustomElementExport;
+
+export interface JavaScriptExport {
+  kind: 'js';
+
   /**
-   * Any class mixins applied in the extends clause of this class.
+   * The name of the exported symbol.
    *
-   * If mixins are applied in the class definition, then the true superclass
-   * of this class is the result of applying mixins in order to the superclass.
+   * JavaScript has a number of ways to export objects which determine the
+   * correct name to use.
    *
-   * Mixins must be listed in order of their application to the superclass or
-   * previous mixin application. This means that the innermost mixin is listed
-   * first. This may read backwards from the common order in JavaScript, but
-   * matches the order of language used to describe mixin application, like
-   * "S with A, B".
-   */
-  mixins?: Reference[]
-  name: string
-  source?: SourceReference
-  /**
-   * A markdown summary suitable for display in a listing.
+   * - Default exports must use the name "default".
+   * - Named exports use the name that is exported. If the export is renamed
+   *   with the "as" clause, use the exported name.
+   * - Aggregating exports (`* from`) should use the name `*`
    */
-  summary?: string
+  name: string;
+
   /**
-   * A reference to an export of a module.
-   *
-   * All references are required to be publically accessible, so the canonical
-   * representation of a reference is the export it's available from.
+   * A reference to the exported declaration.
    *
-   * `package` should generally refer to an npm package name. If `package` is
-   * undefined then the reference is local to this package. If `module` is
-   * undefined the reference is local to the containing module.
-   *
-   * References to global symbols like `Array`, `HTMLElement`, or `Event` should
-   * use a `package` name of `"global:"`.
-   */
-  superclass?: {
-    module?: string
-    name: string
-    package?: string
-    [k: string]: unknown
-  }
-}
-export interface ClassField {
-  default?: string
+   * In the case of aggregating exports, the reference's `module` field must be
+   * defined and the `name` field must be `"*"`.
+   */
+  declaration: Reference;
+
   /**
-   * Whether the property is deprecated.
+   * Whether the export is deprecated. For example, the name of the export was changed.
    * If the value is a string, it's the reason for the deprecation.
    */
-  deprecated?: string | boolean
+  deprecated?: boolean | string;
+}
+
+/**
+ * A global custom element defintion, ie the result of a
+ * `customElements.define()` call.
+ *
+ * This is represented as an export because a definition makes the element
+ * available outside of the module it's defined it.
+ */
+export interface CustomElementExport {
+  kind: 'custom-element-definition';
+
   /**
-   * A markdown description of the field.
+   * The tag name of the custom element.
    */
-  description?: string
-  inheritedFrom?: Reference
-  kind: "field"
-  name: string
-  privacy?: Privacy
+  name: string;
+
   /**
-   * Whether the property is read-only.
+   * A reference to the class or other declaration that implements the
+   * custom element.
    */
-  readonly?: boolean
-  source?: SourceReference
-  static?: boolean
+  declaration: Reference;
+
   /**
-   * A markdown summary suitable for display in a listing.
+   * Whether the custom-element export is deprecated.
+   * For example, a future version will not register the custom element in this file.
+   * If the value is a string, it's the reason for the deprecation.
    */
-  summary?: string
-  type?: Type
+  deprecated?: boolean | string;
 }
+
+export type Declaration =
+  | ClassDeclaration
+  | FunctionDeclaration
+  | MixinDeclaration
+  | VariableDeclaration
+  | CustomElementDeclaration
+  | CustomElementMixinDeclaration;
+
 /**
  * A reference to an export of a module.
  *
@@ -169,10 +177,11 @@ export interface ClassField {
  * use a `package` name of `"global:"`.
  */
 export interface Reference {
-  module?: string
-  name: string
-  package?: string
+  name: string;
+  package?: string;
+  module?: string;
 }
+
 /**
  * A reference to the source of a declaration or member.
  */
@@ -180,437 +189,195 @@ export interface SourceReference {
   /**
    * An absolute URL to the source (ie. a GitHub URL).
    */
-  href: string
+  href: string;
 }
-export interface Type {
+
+/**
+ * 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.
+ *
+ * Note that `tagName` in this interface is optional. Tag names are not
+ * neccessarily part of a custom element class, but belong to the definition
+ * (often called the "registration") or the `customElements.define()` call.
+ *
+ * Because classes and tag names can only be registered once, there's a
+ * one-to-one relationship between classes and tag names. For ease of use,
+ * we allow the tag name here.
+ *
+ * Some packages define and register custom elements in separate modules. In
+ * these cases one `Module` should contain the `CustomElement` without a
+ * tagName, and another `Module` should contain the
+ * `CustomElementExport`.
+ */
+// Note: this needs to be an interface to be included in the generated JSON
+// Schema output.
+export interface CustomElementDeclaration
+  extends ClassDeclaration,
+    CustomElement {}
+
+/**
+ * The additional fields that a custom element adds to classes and mixins.
+ */
+export interface CustomElement extends ClassLike {
   /**
-   * An array of references to the types in the type string.
+   * An optional tag name that should be specified if this is a
+   * self-registering element.
    *
-   * These references have optional indices into the type string so that tools
-   * can understand the references in the type string independently of the type
-   * system and syntax. For example, a documentation viewer could display the
-   * type `Array<FooElement | BarElement>` with cross-references to `FooElement`
-   * and `BarElement` without understanding arrays, generics, or union types.
+   * Self-registering elements must also include a CustomElementExport
+   * in the module's exports.
    */
-  references?: TypeReference[]
-  source?: SourceReference
+  tagName?: string;
+
   /**
-   * The full string representation of the type, in whatever type syntax is
-   * used, such as JSDoc, Closure, or TypeScript.
+   * The attributes that this element is known to understand.
    */
-  text: string
-}
-/**
- * A reference that is associated with a type string and optionally a range
- * within the string.
- *
- * Start and end must both be present or not present. If they're present, they
- * are indices into the associated type string. If they are missing, the entire
- * type string is the symbol referenced and the name should match the type
- * string.
- */
-export interface TypeReference {
-  end?: number
-  module?: string
-  name: string
-  package?: string
-  start?: number
-}
-export interface ClassMethod {
+  attributes?: Attribute[];
+
   /**
-   * Whether the function is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
+   * The events that this element fires.
    */
-  deprecated?: string | boolean
+  events?: Event[];
+
   /**
-   * A markdown description.
+   * The shadow dom content slots that this element accepts.
    */
-  description?: string
-  inheritedFrom?: Reference
-  kind: "method"
-  name: string
-  parameters?: Parameter[]
-  privacy?: Privacy
-  return?: {
-    /**
-     * A markdown description.
-     */
-    description?: string
-    /**
-     * A markdown summary suitable for display in a listing.
-     */
-    summary?: string
-    type?: Type
-    [k: string]: unknown
-  }
-  source?: SourceReference
-  static?: boolean
+  slots?: Slot[];
+
+  cssParts?: CssPart[];
+
+  cssProperties?: CssCustomProperty[];
+
+  demos?: Demo[];
+
   /**
-   * A markdown summary suitable for display in a listing.
+   * Distinguishes a regular JavaScript class from a
+   * custom element class
    */
-  summary?: string
+  customElement: true;
 }
-export interface Parameter {
-  default?: string
+
+export interface Attribute {
+  name: string;
+
   /**
-   * Whether the property is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
+   * A markdown summary suitable for display in a listing.
    */
-  deprecated?: string | boolean
+  summary?: string;
+
   /**
-   * A markdown description of the field.
+   * A markdown description.
    */
-  description?: string
-  name: string
+  description?: string;
+
+  inheritedFrom?: Reference;
+
   /**
-   * Whether the parameter is optional. Undefined implies non-optional.
+   * The type that the attribute will be serialized/deserialized as.
    */
-  optional?: boolean
+  type?: Type;
+
   /**
-   * Whether the property is read-only.
+   * The default value of the attribute, if any.
+   *
+   * As attributes are always strings, this is the actual value, not a human
+   * readable description.
    */
-  readonly?: boolean
+  default?: string;
+
   /**
-   * Whether the parameter is a rest parameter. Only the last parameter may be a rest parameter.
-   * Undefined implies single parameter.
+   * The name of the field this attribute is associated with, if any.
    */
-  rest?: boolean
+  fieldName?: string;
+
   /**
-   * A markdown summary suitable for display in a listing.
+   * Whether the attribute is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
    */
-  summary?: string
-  type?: Type
+  deprecated?: boolean | string;
 }
-export interface FunctionDeclaration {
+
+export interface Event {
+  name: string;
+
   /**
-   * Whether the function is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
+   * A markdown summary suitable for display in a listing.
    */
-  deprecated?: string | boolean
+  summary?: string;
+
   /**
    * A markdown description.
    */
-  description?: string
-  kind: "function"
-  name: string
-  parameters?: Parameter[]
-  return?: {
-    /**
-     * A markdown description.
-     */
-    description?: string
-    /**
-     * A markdown summary suitable for display in a listing.
-     */
-    summary?: string
-    type?: Type
-    [k: string]: unknown
-  }
-  source?: SourceReference
+  description?: string;
+
   /**
-   * A markdown summary suitable for display in a listing.
+   * The type of the event object that's fired.
    */
-  summary?: string
-}
-/**
- * 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 [this article]{@link https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/}
- * for more information on the classmixin pattern in JavaScript.
- */
-export interface MixinDeclaration {
+  type: Type;
+
+  inheritedFrom?: Reference;
+
   /**
-   * Whether the class or mixin is deprecated.
+   * Whether the event is deprecated.
    * If the value is a string, it's the reason for the deprecation.
    */
-  deprecated?: string | boolean
+  deprecated?: boolean | string;
+}
+
+export interface Slot {
   /**
-   * A markdown description of the class.
+   * The slot name, or the empty string for an unnamed slot.
    */
-  description?: string
-  kind: "mixin"
-  members?: (ClassField | ClassMethod)[]
-  /**
-   * Any class mixins applied in the extends clause of this class.
-   *
-   * If mixins are applied in the class definition, then the true superclass
-   * of this class is the result of applying mixins in order to the superclass.
-   *
-   * Mixins must be listed in order of their application to the superclass or
-   * previous mixin application. This means that the innermost mixin is listed
-   * first. This may read backwards from the common order in JavaScript, but
-   * matches the order of language used to describe mixin application, like
-   * "S with A, B".
-   */
-  mixins?: Reference[]
-  name: string
-  parameters?: Parameter[]
-  return?: {
-    /**
-     * A markdown description.
-     */
-    description?: string
-    /**
-     * A markdown summary suitable for display in a listing.
-     */
-    summary?: string
-    type?: Type
-    [k: string]: unknown
-  }
-  source?: SourceReference
-  /**
-   * A markdown summary suitable for display in a listing.
-   */
-  summary?: string
-  /**
-   * A reference to an export of a module.
-   *
-   * All references are required to be publically accessible, so the canonical
-   * representation of a reference is the export it's available from.
-   *
-   * `package` should generally refer to an npm package name. If `package` is
-   * undefined then the reference is local to this package. If `module` is
-   * undefined the reference is local to the containing module.
-   *
-   * References to global symbols like `Array`, `HTMLElement`, or `Event` should
-   * use a `package` name of `"global:"`.
-   */
-  superclass?: {
-    module?: string
-    name: string
-    package?: string
-    [k: string]: unknown
-  }
-}
-export interface VariableDeclaration {
-  default?: string
-  /**
-   * Whether the property is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
-   */
-  deprecated?: string | boolean
-  /**
-   * A markdown description of the field.
-   */
-  description?: string
-  kind: "variable"
-  name: string
-  /**
-   * Whether the property is read-only.
-   */
-  readonly?: boolean
-  source?: SourceReference
-  /**
-   * A markdown summary suitable for display in a listing.
-   */
-  summary?: string
-  type?: Type
-}
-/**
- * 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.
- *
- * Note that `tagName` in this interface is optional. Tag names are not
- * neccessarily part of a custom element class, but belong to the definition
- * (often called the "registration") or the `customElements.define()` call.
- *
- * Because classes and tag names can only be registered once, there's a
- * one-to-one relationship between classes and tag names. For ease of use,
- * we allow the tag name here.
- *
- * Some packages define and register custom elements in separate modules. In
- * these cases one `Module` should contain the `CustomElement` without a
- * tagName, and another `Module` should contain the
- * `CustomElementExport`.
- */
-export interface CustomElementDeclaration {
-  /**
-   * The attributes that this element is known to understand.
-   */
-  attributes?: Attribute[]
-  cssParts?: CssPart[]
-  cssProperties?: CssCustomProperty[]
-  /**
-   * Distinguishes a regular JavaScript class from a
-   * custom element class
-   */
-  customElement: true
-  demos?: Demo[]
-  /**
-   * Whether the class or mixin is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
-   */
-  deprecated?: string | boolean
-  /**
-   * A markdown description of the class.
-   */
-  description?: string
-  /**
-   * The events that this element fires.
-   */
-  events?: Event[]
-  kind: "class"
-  members?: (ClassField | ClassMethod)[]
-  /**
-   * Any class mixins applied in the extends clause of this class.
-   *
-   * If mixins are applied in the class definition, then the true superclass
-   * of this class is the result of applying mixins in order to the superclass.
-   *
-   * Mixins must be listed in order of their application to the superclass or
-   * previous mixin application. This means that the innermost mixin is listed
-   * first. This may read backwards from the common order in JavaScript, but
-   * matches the order of language used to describe mixin application, like
-   * "S with A, B".
-   */
-  mixins?: Reference[]
-  name: string
-  /**
-   * The shadow dom content slots that this element accepts.
-   */
-  slots?: Slot[]
-  source?: SourceReference
+  name: string;
+
   /**
    * A markdown summary suitable for display in a listing.
    */
-  summary?: string
-  /**
-   * A reference to an export of a module.
-   *
-   * All references are required to be publically accessible, so the canonical
-   * representation of a reference is the export it's available from.
-   *
-   * `package` should generally refer to an npm package name. If `package` is
-   * undefined then the reference is local to this package. If `module` is
-   * undefined the reference is local to the containing module.
-   *
-   * References to global symbols like `Array`, `HTMLElement`, or `Event` should
-   * use a `package` name of `"global:"`.
-   */
-  superclass?: {
-    module?: string
-    name: string
-    package?: string
-    [k: string]: unknown
-  }
-  /**
-   * An optional tag name that should be specified if this is a
-   * self-registering element.
-   *
-   * Self-registering elements must also include a CustomElementExport
-   * in the module's exports.
-   */
-  tagName?: string
-}
-export interface Attribute {
-  /**
-   * The default value of the attribute, if any.
-   *
-   * As attributes are always strings, this is the actual value, not a human
-   * readable description.
-   */
-  default?: string
-  /**
-   * Whether the attribute is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
-   */
-  deprecated?: string | boolean
+  summary?: string;
+
   /**
    * A markdown description.
    */
-  description?: string
-  /**
-   * The name of the field this attribute is associated with, if any.
-   */
-  fieldName?: string
-  inheritedFrom?: Reference
-  name: string
-  /**
-   * A markdown summary suitable for display in a listing.
-   */
-  summary?: string
+  description?: string;
+
   /**
-   * The type that the attribute will be serialized/deserialized as.
+   * Whether the slot is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
    */
-  type?: {
-    /**
-     * An array of references to the types in the type string.
-     *
-     * These references have optional indices into the type string so that tools
-     * can understand the references in the type string independently of the type
-     * system and syntax. For example, a documentation viewer could display the
-     * type `Array<FooElement | BarElement>` with cross-references to `FooElement`
-     * and `BarElement` without understanding arrays, generics, or union types.
-     */
-    references?: TypeReference[]
-    source?: SourceReference
-    /**
-     * The full string representation of the type, in whatever type syntax is
-     * used, such as JSDoc, Closure, or TypeScript.
-     */
-    text: string
-    [k: string]: unknown
-  }
+  deprecated?: boolean | string;
 }
+
 /**
  * The description of a CSS Part
  */
 export interface CssPart {
+  name: string;
+
   /**
-   * Whether the CSS shadow part is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
+   * A markdown summary suitable for display in a listing.
    */
-  deprecated?: string | boolean
+  summary?: string;
+
   /**
    * A markdown description.
    */
-  description?: string
-  name: string
+  description?: string;
+
   /**
-   * A markdown summary suitable for display in a listing.
+   * Whether the CSS shadow part is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
    */
-  summary?: string
+  deprecated?: boolean | string;
 }
+
 export interface CssCustomProperty {
-  default?: string
-  /**
-   * Whether the CSS custom property is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
-   */
-  deprecated?: string | boolean
-  /**
-   * A markdown description.
-   */
-  description?: string
   /**
    * The name of the property, including leading `--`.
    */
-  name: string
-  /**
-   * A markdown summary suitable for display in a listing.
-   */
-  summary?: string
+  name: string;
+
   /**
    * The expected syntax of the defined property. Defaults to "*".
    *
@@ -624,109 +391,87 @@ export interface CssCustomProperty {
    * "small | medium | large": accepts one of these values set as custom idents.
    * "*": any valid token
    */
-  syntax?: string
-}
-export interface Demo {
-  /**
-   * A markdown description of the demo.
-   */
-  description?: string
-  source?: SourceReference
-  /**
-   * Relative URL of the demo if it's published with the package. Absolute URL
-   * if it's hosted.
-   */
-  url: string
-}
-export interface Event {
-  /**
-   * Whether the event is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
-   */
-  deprecated?: string | boolean
-  /**
-   * A markdown description.
-   */
-  description?: string
-  inheritedFrom?: Reference
-  name: string
+  syntax?: string;
+
+  default?: string;
+
   /**
    * A markdown summary suitable for display in a listing.
    */
-  summary?: string
+  summary?: string;
+
   /**
-   * The type of the event object that's fired.
+   * A markdown description.
    */
-  type: {
-    /**
-     * An array of references to the types in the type string.
-     *
-     * These references have optional indices into the type string so that tools
-     * can understand the references in the type string independently of the type
-     * system and syntax. For example, a documentation viewer could display the
-     * type `Array<FooElement | BarElement>` with cross-references to `FooElement`
-     * and `BarElement` without understanding arrays, generics, or union types.
-     */
-    references?: TypeReference[]
-    source?: SourceReference
-    /**
-     * The full string representation of the type, in whatever type syntax is
-     * used, such as JSDoc, Closure, or TypeScript.
-     */
-    text: string
-    [k: string]: unknown
-  }
-}
-export interface Slot {
+  description?: string;
+
   /**
-   * Whether the slot is deprecated.
+   * Whether the CSS custom property is deprecated.
    * If the value is a string, it's the reason for the deprecation.
    */
-  deprecated?: string | boolean
-  /**
-   * A markdown description.
-   */
-  description?: string
+  deprecated?: boolean | string;
+}
+
+export interface Type {
   /**
-   * The slot name, or the empty string for an unnamed slot.
+   * The full string representation of the type, in whatever type syntax is
+   * used, such as JSDoc, Closure, or TypeScript.
    */
-  name: string
+  text: string;
+
   /**
-   * A markdown summary suitable for display in a listing.
+   * An array of references to the types in the type string.
+   *
+   * These references have optional indices into the type string so that tools
+   * can understand the references in the type string independently of the type
+   * system and syntax. For example, a documentation viewer could display the
+   * type `Array<FooElement | BarElement>` with cross-references to `FooElement`
+   * and `BarElement` without understanding arrays, generics, or union types.
    */
-  summary?: string
+  references?: TypeReference[];
+
+  source?: SourceReference;
 }
+
 /**
- * A class mixin that also adds custom element related properties.
+ * A reference that is associated with a type string and optionally a range
+ * within the string.
+ *
+ * Start and end must both be present or not present. If they're present, they
+ * are indices into the associated type string. If they are missing, the entire
+ * type string is the symbol referenced and the name should match the type
+ * string.
  */
-export interface CustomElementMixinDeclaration {
-  /**
-   * The attributes that this element is known to understand.
-   */
-  attributes?: Attribute[]
-  cssParts?: CssPart[]
-  cssProperties?: CssCustomProperty[]
-  /**
-   * Distinguishes a regular JavaScript class from a
-   * custom element class
-   */
-  customElement: true
-  demos?: Demo[]
+export interface TypeReference extends Reference {
+  start?: number;
+  end?: number;
+}
+
+/**
+ * The common interface of classes and mixins.
+ */
+export interface ClassLike {
+  name: string;
+
   /**
-   * Whether the class or mixin is deprecated.
-   * If the value is a string, it's the reason for the deprecation.
+   * A markdown summary suitable for display in a listing.
    */
-  deprecated?: string | boolean
+  summary?: string;
+
   /**
    * A markdown description of the class.
    */
-  description?: string
+  description?: string;
+
   /**
-   * The events that this element fires.
+   * The superclass of this class.
+   *
+   * If this class is defined with mixin applications, the prototype chain
+   * includes the mixin applications and the true superclass is computed
+   * from them.
    */
-  events?: Event[]
-  kind: "mixin"
-  members?: (ClassField | ClassMethod)[]
+  superclass?: Reference;
+
   /**
    * Any class mixins applied in the extends clause of this class.
    *
@@ -738,134 +483,254 @@ export interface CustomElementMixinDeclaration {
    * first. This may read backwards from the common order in JavaScript, but
    * matches the order of language used to describe mixin application, like
    * "S with A, B".
-   */
-  mixins?: Reference[]
-  name: string
-  parameters?: Parameter[]
-  return?: {
-    /**
-     * A markdown description.
-     */
-    description?: string
-    /**
-     * A markdown summary suitable for display in a listing.
-     */
-    summary?: string
-    type?: Type
-    [k: string]: unknown
-  }
+   *
+   * @example
+   *
+   * ```javascript
+   * class T extends B(A(S)) {}
+   * ```
+   *
+   * is described by:
+   * ```json
+   * {
+   *   "kind": "class",
+   *   "superclass": {
+   *     "name": "S"
+   *   },
+   *   "mixins": [
+   *     {
+   *       "name": "A"
+   *     },
+   *     {
+   *       "name": "B"
+   *     },
+   *   ]
+   * }
+   * ```
+   */
+  mixins?: Array<Reference>;
+  members?: Array<ClassMember>;
+
+  source?: SourceReference;
+
   /**
-   * The shadow dom content slots that this element accepts.
+   * Whether the class or mixin is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
    */
-  slots?: Slot[]
-  source?: SourceReference
+  deprecated?: boolean | string;
+}
+
+export interface ClassDeclaration extends ClassLike {
+  kind: 'class';
+}
+
+export type ClassMember = ClassField | ClassMethod;
+
+/**
+ * The common interface of variables, class fields, and function
+ * parameters.
+ */
+export interface PropertyLike {
+  name: string;
+
   /**
    * A markdown summary suitable for display in a listing.
    */
-  summary?: string
+  summary?: string;
+
   /**
-   * A reference to an export of a module.
-   *
-   * All references are required to be publically accessible, so the canonical
-   * representation of a reference is the export it's available from.
-   *
-   * `package` should generally refer to an npm package name. If `package` is
-   * undefined then the reference is local to this package. If `module` is
-   * undefined the reference is local to the containing module.
-   *
-   * References to global symbols like `Array`, `HTMLElement`, or `Event` should
-   * use a `package` name of `"global:"`.
+   * A markdown description of the field.
    */
-  superclass?: {
-    module?: string
-    name: string
-    package?: string
-    [k: string]: unknown
-  }
+  description?: string;
+
+  type?: Type;
+
+  default?: string;
+
   /**
-   * An optional tag name that should be specified if this is a
-   * self-registering element.
-   *
-   * Self-registering elements must also include a CustomElementExport
-   * in the module's exports.
+   * Whether the property is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
    */
-  tagName?: string
-}
-export interface JavaScriptExport {
+  deprecated?: boolean | string;
+
   /**
-   * A reference to an export of a module.
-   *
-   * All references are required to be publically accessible, so the canonical
-   * representation of a reference is the export it's available from.
-   *
-   * `package` should generally refer to an npm package name. If `package` is
-   * undefined then the reference is local to this package. If `module` is
-   * undefined the reference is local to the containing module.
-   *
-   * References to global symbols like `Array`, `HTMLElement`, or `Event` should
-   * use a `package` name of `"global:"`.
+   * Whether the property is read-only.
    */
-  declaration: {
-    module?: string
-    name: string
-    package?: string
-    [k: string]: unknown
-  }
+  readonly?: boolean;
+}
+
+export interface ClassField extends PropertyLike {
+  kind: 'field';
+  static?: boolean;
+  privacy?: Privacy;
+  inheritedFrom?: Reference;
+  source?: SourceReference;
+}
+
+/**
+ * Additional metadata for fields on custom elements.
+ */
+export interface CustomElementField extends ClassField {
   /**
-   * Whether the export is deprecated. For example, the name of the export was changed.
-   * If the value is a string, it's the reason for the deprecation.
+   * The corresponding attribute name if there is one.
+   * 
+   * If this property is defined, the attribute must be listed in the classes'
+   * `attributes` array.
    */
-  deprecated?: string | boolean
-  kind: "js"
+  attribute?: string;
+
   /**
-   * The name of the exported symbol.
-   *
-   * JavaScript has a number of ways to export objects which determine the
-   * correct name to use.
+   * If the property reflects to an attribute.
    *
-   * - Default exports must use the name "default".
-   * - Named exports use the name that is exported. If the export is renamed
-   *   with the "as" clause, use the exported name.
-   * - Aggregating exports (`* from`) should use the name `*`
+   * If this is true, the `attribute` property must be defined.
    */
-  name: string
+  reflects?: boolean;
+}
+
+export interface ClassMethod extends FunctionLike {
+  kind: 'method';
+  static?: boolean;
+  privacy?: Privacy;
+  inheritedFrom?: Reference;
+  source?: SourceReference;
 }
+
 /**
- * A global custom element defintion, ie the result of a
- * `customElements.define()` call.
+ * A description of a class mixin.
  *
- * This is represented as an export because a definition makes the element
- * available outside of the module it's defined it.
+ * 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 [this article]{@link https://justinfagnani.com/2015/12/21/real-mixins-with-javascript-classes/}
+ * for more information on the classmixin pattern in JavaScript.
+ *
+ * @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",
+ *     }
+ *   ]
+ * }
+ * ```
  */
-export interface CustomElementExport {
+export interface MixinDeclaration extends ClassLike, FunctionLike {
+  kind: 'mixin';
+}
+
+/**
+ * A class mixin that also adds custom element related properties.
+ */
+// Note: this needs to be an interface to be included in the generated JSON
+// Schema output.
+export interface CustomElementMixinDeclaration
+  extends MixinDeclaration,
+    CustomElement {}
+
+export interface VariableDeclaration extends PropertyLike {
+  kind: 'variable';
+  source?: SourceReference;
+}
+
+export interface FunctionDeclaration extends FunctionLike {
+  kind: 'function';
+  source?: SourceReference;
+}
+
+export interface Parameter extends PropertyLike {
   /**
-   * A reference to an export of a module.
-   *
-   * All references are required to be publically accessible, so the canonical
-   * representation of a reference is the export it's available from.
-   *
-   * `package` should generally refer to an npm package name. If `package` is
-   * undefined then the reference is local to this package. If `module` is
-   * undefined the reference is local to the containing module.
-   *
-   * References to global symbols like `Array`, `HTMLElement`, or `Event` should
-   * use a `package` name of `"global:"`.
+   * Whether the parameter is optional. Undefined implies non-optional.
    */
-  declaration: {
-    module?: string
-    name: string
-    package?: string
-    [k: string]: unknown
-  }
+  optional?: boolean;
   /**
-   * Whether the custom-element export is deprecated.
-   * For example, a future version will not register the custom element in this file.
-   * If the value is a string, it's the reason for the deprecation.
+   * Whether the parameter is a rest parameter. Only the last parameter may be a rest parameter.
+   * Undefined implies single parameter.
+   */
+  rest?: boolean;
+}
+
+export interface FunctionLike {
+  name: string;
+
+  /**
+   * A markdown summary suitable for display in a listing.
+   */
+  summary?: string;
+
+  /**
+   * A markdown description.
    */
-  deprecated?: string | boolean
-  kind: "custom-element-definition"
+  description?: string;
+
   /**
-   * The tag name of the custom element.
+   * Whether the function is deprecated.
+   * If the value is a string, it's the reason for the deprecation.
    */
-  name: string
+  deprecated?: boolean | string;
+
+  parameters?: Parameter[];
+
+  return?: {
+    type?: Type;
+
+    /**
+     * A markdown summary suitable for display in a listing.
+     */
+    summary?: string;
+
+    /**
+     * A markdown description.
+     */
+    description?: string;
+  };
 }
+
+export type Privacy = 'public' | 'private' | 'protected';
+
+export interface Demo {
+  /**
+   * A markdown description of the demo.
+   */
+  description?: string;
+
+  /**
+   * Relative URL of the demo if it's published with the package. Absolute URL
+   * if it's hosted.
+   */
+  url: string;
+
+  source?: SourceReference;
+}