@arcgis/api-extractor 4.33.0-next.99 → 4.34.0-next.0

package/dist/apiJson.d.ts

@@ -88,6 +88,10 @@ export type ApiJavaScriptModule = {
     path: 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;
     /**
@@ -176,6 +180,9 @@ export type ApiCustomElementExport = {
      * If the value is a string, it's the reason for the deprecation.
      *
      * @default false
+     * @remarks
+     * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
+     * with custom-elements-manifest.
      */
     deprecated?: boolean | string;
 };
@@ -245,7 +252,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 = ApiClassDeclaration & {
+export type ApiCustomElementDeclaration = Omit<ApiClassDeclaration, "members"> & {
     /**
      * An optional tag name that should be specified if this is a
      * self-registering element.
@@ -347,6 +354,10 @@ export type ApiAttribute = {
     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;
     /**
@@ -388,6 +399,10 @@ export type ApiEvent = {
     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;
     /**
@@ -452,6 +467,10 @@ export type ApiSlot = {
     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;
     /**
@@ -482,6 +501,10 @@ export type ApiCssPart = {
     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;
     /**
@@ -515,6 +538,10 @@ export type ApiCssCustomState = {
     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;
     /**
@@ -558,6 +585,10 @@ export type ApiCssCustomProperty = {
     default?: 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;
     /**
@@ -645,6 +676,10 @@ export type ApiClassDeclaration = {
     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;
     /**
@@ -735,6 +770,10 @@ export type ApiPropertyLike = {
     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;
     /**
@@ -996,6 +1035,10 @@ export type ApiFunctionLike = {
     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;
     /**
@@ -1017,6 +1060,10 @@ export type ApiFunctionLike = {
         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;
         /**
@@ -1031,11 +1078,6 @@ export type ApiFunctionLike = {
  * with custom-elements-manifest.
  */
 export type ApiPrivacy = "private" | "protected" | "public";
-/**
- * @remarks
- * Not used by `@arcgis/api-extractor`. Preserved in typings for compatibility
- * with custom-elements-manifest.
- */
 export type ApiDemo = {
     /**
      * A markdown description of the demo.

package/dist/extractor/index.d.ts

@@ -1,5 +1,6 @@
-import { ApiDeclaration, ApiExport, ApiJson, ApiModule } from '../apiJson';
+import { ApiClassMethod, ApiCustomElementDeclaration, ApiCustomElementField, ApiDeclaration, ApiEvent, ApiExport, ApiJson, ApiModule } from '../apiJson';
 import { default as ts } from 'typescript';
+import { CopyPropertyDoc, CopyMethodDoc, CopyEventDoc } from '../types';
 export type ApiExtractorOptions = {
     /**
      * Whether to extract full API information, with type-checking. This should be
@@ -39,4 +40,7 @@ export declare abstract class ApiExtractor {
      * Infer ApiExport based on ApiDeclaration
      */
     protected abstract inferExport(declaration: ApiDeclaration): ApiExport | undefined;
+    copyDoc(copyDocDefinition: CopyPropertyDoc | undefined, property: ApiCustomElementField, component: ApiCustomElementDeclaration): void;
+    copyDoc(copyDocDefinition: CopyMethodDoc | undefined, method: ApiClassMethod, component: ApiCustomElementDeclaration): void;
+    copyDoc(copyDocDefinition: CopyEventDoc | undefined, event: ApiEvent, component: ApiCustomElementDeclaration): void;
 }

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { ApiExtractor, type ApiExtractorOptions } from './extractor';
 export type * from './apiJson';
-export { hasIgnoredModifier, setDefaultFromInitializer, getMemberName } from './utils/astHelpers';
-export { isApiMethod, isApiProperty, globalPackageIdentifier } from './utils/apiHelpers';
+export { hasIgnoredModifier, setDefaultFromInitializer, getMemberName, findDecorator } from './utils/astHelpers';
+export { isApiMethod, isApiProperty, globalPackageIdentifier, multipleJsDocTags } from './utils/apiHelpers';
+export type { CopyDocDefinitions } from './types';
+export { symbolToDocs, apiMemberToSynthesizedComments, setApiDocFromJsDoc } from './utils/docHelpers';

package/dist/index.js

@@ -1,95 +1,242 @@
-import o from "typescript";
-import { path as d } from "@arcgis/components-build-utils";
-const p = "@arcgis/api-extractor", f = "4.33.0-next.99", g = (t) => t.kind === "method", S = (t) => t.kind === "field";
-function u(t, i) {
-  const e = t.path.split("/"), r = e.pop(), s = e.join("/"), a = i.path.split("/"), l = a.pop(), n = a.join("/");
-  return s === n ? r < l ? -1 : 1 : s.startsWith(n) ? 1 : n.startsWith(s) || s < n ? -1 : 1;
+import a from "typescript";
+import { path as x } from "@arcgis/components-build-utils";
+import { mappedFind as m } from "@arcgis/components-utils";
+const h = "@arcgis/api-extractor", g = "4.34.0-next.0", j = (e) => e.kind === "method", A = (e) => e.kind === "field";
+function v(e, s) {
+  const t = e.path.split("/"), n = t.pop(), i = t.join("/"), o = s.path.split("/"), c = o.pop(), r = o.join("/");
+  return i === r ? n < c ? -1 : 1 : i.startsWith(r) ? 1 : r.startsWith(i) || i < r ? -1 : 1;
 }
-const k = "global:";
-class y {
-  constructor(i) {
-    this.options = i;
+const C = "global:", T = /* @__PURE__ */ new Set([
+  "example",
+  "see",
+  "param",
+  "property",
+  "throws",
+  "slot",
+  "csspart",
+  "cssstate"
+]);
+class F {
+  constructor(s) {
+    this.options = s;
   }
   /** Given an array of TypeScript source files, generate an api.json file */
-  extract(i) {
+  extract(s) {
     return {
       timestamp: (/* @__PURE__ */ new Date()).toISOString().split(".")[0],
       compiler: {
-        name: p,
-        version: f,
-        typescriptVersion: o.version
+        name: h,
+        version: g,
+        typescriptVersion: a.version
       },
       schemaVersion: "1.0.0",
-      modules: this.extractModules(i)
+      modules: this.extractModules(s)
     };
   }
-  extractModules(i) {
-    const e = [];
-    for (const r of i)
-      this.file = r, e.push(this.extractModule(r));
-    return this.options.isFullApiExtraction && e.sort(u), e;
+  extractModules(s) {
+    const t = [];
+    for (const n of s)
+      this.file = n, t.push(this.extractModule(n));
+    return this.options.isFullApiExtraction && t.sort(v), t;
   }
-  extractModule(i) {
-    const e = {
+  extractModule(s) {
+    const t = {
       kind: "javascript-module",
-      path: d.relative(this.options.cwd, i.fileName),
+      path: x.relative(this.options.cwd, s.fileName),
       declarations: void 0,
       exports: void 0
     };
-    this.apiModule = e;
-    const r = this.extractDeclarations(i);
-    if (e.declarations = r, this.options.isFullApiExtraction) {
-      const s = this.inferExports(r);
-      s.length > 0 && (e.exports = s);
+    this.apiModule = t;
+    const n = this.extractDeclarations(s);
+    if (t.declarations = n, this.options.isFullApiExtraction) {
+      const i = this.inferExports(n);
+      i.length > 0 && (t.exports = i);
     }
-    return e;
+    return t;
   }
   /**
    * For a given module, extract all public declarations.
    */
-  extractDeclarations(i) {
-    const e = [];
-    for (const r of i.statements) {
-      const s = this.extractDeclaration(r);
-      s !== void 0 && e.push(s);
+  extractDeclarations(s) {
+    const t = [];
+    for (const n of s.statements) {
+      const i = this.extractDeclaration(n);
+      i !== void 0 && t.push(i);
     }
-    return e;
+    return t;
   }
   /**
    * Infer ApiModule.exports based on ApiModule.declarations.
    */
-  inferExports(i) {
-    const e = [];
-    for (const r of i) {
-      const s = this.inferExport(r);
-      s !== void 0 && e.push(s);
+  inferExports(s) {
+    const t = [];
+    for (const n of s) {
+      const i = this.inferExport(n);
+      i !== void 0 && t.push(i);
     }
-    return e;
+    return t;
+  }
+  copyDoc(s, t, n) {
+    const i = t.docsTags?.findIndex((r) => r.name === "copyDoc");
+    if (i === void 0 || i === -1)
+      return;
+    if (s === void 0)
+      throw Error(
+        `The ${t.name} ${"kind" in t ? t.kind : "event"} in ${n.name} has @copyDoc tag, but failed to find copyDoc definition for it.`
+      );
+    const o = s?.(t, n);
+    if (o === void 0)
+      return;
+    for (const [r, d] of Object.entries(o))
+      r !== "docsTags" && (t[r] = t[r] ?? d);
+    t.docsTags.splice(i, 1);
+    const c = new Set(t.docsTags.map(({ name: r }) => r));
+    for (const r of o.docsTags ?? [])
+      c.has(r.name) && !T.has(r.name) || t.docsTags.push(r);
+    t.docsTags.length === 0 && (t.docsTags = void 0);
   }
 }
-const E = (t) => t.modifiers?.some?.(
-  (i) => i.kind === o.SyntaxKind.StaticKeyword || i.kind === o.SyntaxKind.PrivateKeyword || i.kind === o.SyntaxKind.ProtectedKeyword
+const N = (e) => e.modifiers?.some?.(
+  (s) => s.kind === a.SyntaxKind.StaticKeyword || s.kind === a.SyntaxKind.PrivateKeyword || s.kind === a.SyntaxKind.ProtectedKeyword
 ) ?? !1;
-function v(t, i, e) {
-  if (!i.default && "initializer" in t && t.initializer) {
-    const r = c(t.initializer);
-    x(r) && (i.default = r.getText(e));
+function O(e, s, t) {
+  if (!s.default && "initializer" in e && e.initializer) {
+    const n = u(e.initializer);
+    y(n) && (s.default = n.getText(t));
+  }
+}
+const y = (e) => a.isLiteralExpression(e) || e.kind === a.SyntaxKind.TrueKeyword || e.kind === a.SyntaxKind.FalseKeyword || a.isPrefixUnaryExpression(e) && a.isLiteralExpression(e.operand);
+function u(e) {
+  return a.isSatisfiesExpression(e) || a.isParenthesizedExpression(e) ? u(e.expression) : e;
+}
+function b(e) {
+  if (e !== void 0 && (a.isIdentifier(e) || a.isStringLiteralLike(e)))
+    return e.text;
+}
+const W = ({ modifiers: e = [] }, s) => m(
+  e,
+  (t) => a.isDecorator(t) && a.isCallExpression(t.expression) && a.isIdentifier(t.expression.expression) && t.expression.expression.text === s ? t.expression : void 0
+);
+function S(e, s) {
+  const t = $(s.getJsDocTags());
+  let n = a.displayPartsToString(s.getDocumentationComment(e));
+  const i = t.at(-1), o = i?.text?.indexOf(k);
+  if (o !== void 0 && o !== -1) {
+    const c = i.text.indexOf(D);
+    c !== -1 && (n += i.text.slice(c), i.text = i.text?.slice(0, c));
+  }
+  return {
+    docsTags: t,
+    description: n || void 0
+  };
+}
+const D = `
+
+{@link `, k = "Read more...}", $ = (e) => e.map((s) => ({
+  name: s.name,
+  text: s.text?.map((t) => t.text).join("")
+}));
+function J(e) {
+  const s = Array.from(e.docsTags ?? []), t = e, n = e;
+  if (e.deprecated && s.push({
+    name: "deprecated",
+    text: e.deprecated === !0 ? void 0 : e.deprecated
+  }), t.default && s.push({
+    name: "default",
+    text: t.default
+  }), n.cssParts)
+    for (const o of n.cssParts)
+      s.push({
+        name: "csspart",
+        text: f(o)
+      });
+  if (n.cssStates)
+    for (const o of n.cssStates)
+      s.push({
+        name: "cssstate",
+        text: f(o)
+      });
+  if (n.slots)
+    for (const o of n.slots)
+      s.push({
+        name: "slot",
+        text: f(o)
+      });
+  n.privacy === "private" && s.push({
+    name: "private",
+    text: void 0
+  });
+  const i = e.description ?? "";
+  return s.length === 0 && i.length === 0 ? [] : [E(i, s)];
+}
+function E(e = "", s = []) {
+  return {
+    kind: a.SyntaxKind.MultiLineCommentTrivia,
+    pos: -1,
+    end: -1,
+    text: I(e, s),
+    hasTrailingNewLine: !0
+  };
+}
+function I(e = "", s = []) {
+  const t = e === "" ? [] : e.split(`
+`), i = t.length + s.length > 1 || (s.at(0)?.text?.includes(`
+`) ?? !1);
+  return `*${i ? t.map((o) => `
+ * ${o}`).join("") : ` ${e}`}${t.length > 0 && s.length > 0 ? `
+ *` : ""}${s.map((o) => {
+    const c = `@${o.name}`, r = o.text ?? "", d = o.text?.includes(`
+`) ?? !1;
+    return `${i ? `
+ * ` : ""}${c}${d ? r.split(`
+`).map((p) => `
+ * ${p}`).join("") : r.length > 0 ? ` ${r}` : ""}`;
+  }).join("")}${i ? `
+` : ""} `;
+}
+function V(e, s, t, n) {
+  const i = s.getSymbolAtLocation(e);
+  if (n ??= i === void 0 ? void 0 : S(s, i), n !== void 0) {
+    for (const o of n.docsTags) {
+      const { name: c, text: r } = o;
+      c === "deprecated" ? t.deprecated = r || !0 : c === "default" ? t.default = r : c === "readonly" ? t.readonly = !0 : c === "private" ? t.privacy = "private" : c === "csspart" ? t.cssParts.push(l(r)) : c === "cssstate" ? t.cssStates.push(l(r)) : c === "slot" ? t.slots.push(l(r)) : (t.docsTags ??= [], t.docsTags.push(o));
+    }
+    t.description = n.description;
   }
 }
-const x = (t) => o.isLiteralExpression(t) || t.kind === o.SyntaxKind.TrueKeyword || t.kind === o.SyntaxKind.FalseKeyword || o.isPrefixUnaryExpression(t) && o.isLiteralExpression(t.operand);
-function c(t) {
-  return o.isSatisfiesExpression(t) || o.isParenthesizedExpression(t) ? c(t.expression) : t;
+function l(e) {
+  if (e === void 0)
+    return { name: "" };
+  const s = e.indexOf(" - ");
+  if (s === -1)
+    return e.startsWith("- ") ? { name: "", description: e.slice(2) } : { name: e };
+  let t, n = e.slice(0, s);
+  if (n.startsWith("[") && n.endsWith("]")) {
+    const o = n.slice(1, -1), c = o.indexOf("=");
+    n = o.slice(0, c), t = o.slice(c + 1);
+  }
+  const i = e.slice(s + 3);
+  return {
+    name: n,
+    default: t,
+    description: i
+  };
 }
-function K(t) {
-  if (t !== void 0 && (o.isIdentifier(t) || o.isStringLiteralLike(t)))
-    return t.text;
+function f(e) {
+  const s = e.name + (e.default !== void 0 ? `=${e.default}` : ""), t = s.length > 0 ? `[${s}]` : "", n = e.description ?? "", i = n.length > 0 ? ` - ${n}` : "";
+  return `${t}${i}`;
 }
 export {
-  y as ApiExtractor,
-  K as getMemberName,
-  k as globalPackageIdentifier,
-  E as hasIgnoredModifier,
-  g as isApiMethod,
-  S as isApiProperty,
-  v as setDefaultFromInitializer
+  F as ApiExtractor,
+  J as apiMemberToSynthesizedComments,
+  W as findDecorator,
+  b as getMemberName,
+  C as globalPackageIdentifier,
+  N as hasIgnoredModifier,
+  j as isApiMethod,
+  A as isApiProperty,
+  T as multipleJsDocTags,
+  V as setApiDocFromJsDoc,
+  O as setDefaultFromInitializer,
+  S as symbolToDocs
 };

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+import { ApiCustomElementField, ApiCustomElementDeclaration, ApiClassMethod, ApiEvent } from './apiJson';
+/**
+ * @example
+ * ```ts
+ * {
+ *   properties: {
+ *     // You only need to return the fields you wish to modify.
+ *     autoDestroyDisabled: () => ({
+ *       description: `If true, the component will not be destroyed automatically when it is
+ * disconnected from the document. This is useful when you want to move the
+ * component to a different place on the page, or temporarily hide it. If this
+ * is set, make sure to call the {@link #destroy} method when you are done to
+ * prevent memory leaks.`,
+ *     }),
+ *   },
+ * }
+ */
+export type CopyDocDefinitions = {
+    properties?: Record<string, CopyPropertyDoc | undefined>;
+    methods?: Record<string, CopyMethodDoc | undefined>;
+    events?: Record<string, CopyEventDoc | undefined>;
+};
+export type CopyPropertyDoc = (property: ApiCustomElementField, component: ApiCustomElementDeclaration) => Partial<ApiCustomElementField> | undefined;
+export type CopyMethodDoc = (method: ApiClassMethod, component: ApiCustomElementDeclaration) => Partial<ApiClassMethod> | undefined;
+export type CopyEventDoc = (event: ApiEvent, component: ApiCustomElementDeclaration) => Partial<ApiEvent> | undefined;

package/dist/utils/apiHelpers.d.ts

@@ -20,3 +20,4 @@ export declare function naturalSortModules(left: ApiModule, right: ApiModule): n
  * This is not made up by us - defined in the custom-elements-manifest spec
  */
 export declare const globalPackageIdentifier = "global:";
+export declare const multipleJsDocTags: Set<string>;

package/dist/utils/astHelpers.d.ts

@@ -10,3 +10,6 @@ export declare function setDefaultFromInitializer(node: ts.AccessorDeclaration |
  * StringLiteralLike nodes. The rest return undefined.
  */
 export declare function getMemberName(name?: ts.PropertyName): string | undefined;
+export declare const findDecorator: ({ modifiers }: {
+    modifiers?: readonly ts.ModifierLike[];
+}, name: string) => ts.CallExpression | undefined;

package/dist/utils/docHelpers.d.ts

@@ -0,0 +1,9 @@
+import { default as ts } from 'typescript';
+import { ApiCustomElementField, ApiCustomElementDeclaration, ApiEvent, ApiDocsTag, ApiCustomElementMember } from '../apiJson';
+export declare function symbolToDocs(checker: ts.TypeChecker, symbol: ts.Signature | ts.Symbol): {
+    description: ApiCustomElementField["description"];
+    docsTags: ApiDocsTag[];
+};
+export declare const internalJsDocTag = "internal";
+export declare function apiMemberToSynthesizedComments(apiMember: ApiCustomElementDeclaration | ApiCustomElementMember | ApiEvent): ts.SynthesizedComment[];
+export declare function setApiDocFromJsDoc(node: ts.PropertyName, checker: ts.TypeChecker, api: Partial<Pick<ApiCustomElementDeclaration, "cssParts" | "cssProperties" | "cssStates" | "slots"> & Pick<ApiCustomElementField, "default" | "deprecated" | "description" | "docsTags" | "privacy" | "readonly">>, docs?: ReturnType<typeof symbolToDocs>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/api-extractor",
-  "version": "4.33.0-next.99",
+  "version": "4.34.0-next.0",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -14,9 +14,9 @@
   ],
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
-    "@arcgis/components-build-utils": "4.33.0-next.99",
-    "@arcgis/components-utils": "4.33.0-next.99",
-    "tslib": "^2.7.0",
-    "typescript": "~5.6.3"
+    "@arcgis/components-build-utils": "4.34.0-next.0",
+    "@arcgis/components-utils": "4.34.0-next.0",
+    "tslib": "^2.8.1",
+    "typescript": "~5.8.3"
   }
 }