@arcgis/api-extractor 5.1.0-next.1 → 5.1.0-next.100

package/dist/apiJson.d.ts

@@ -328,6 +328,13 @@ export interface ApiCustomElementDeclaration extends ApiClassDeclaration, ApiWit
    * @example "ArcgisCounter" (even if class name is `Counter`)
    */
   pascalCaseName: string;
+  /**
+   * True if the custom element is
+   * [form-associated](https://html.spec.whatwg.org/dev/custom-elements.html).
+   *
+   * @default false
+   */
+  formAssociated?: boolean;
   members: ApiCustomElementMember[];
   /**
    * The attributes that this element is known to understand.
@@ -651,7 +658,7 @@ export interface ApiClassDeclaration extends ApiObjectLikeDeclaration, ApiWithEv
    * matches the order of language used to describe mixin application, like
    * "S with A, B".
    *
-   * @see https://webgis.esri.com/webgis/core/core/mixins
+   * @see https://webgis.esri.com/sdk/contributing/core/core/mixins
    */
   mixins?: ApiReferenceWithTypeArguments[];
 }
@@ -778,7 +785,7 @@ export interface ApiClassMethod extends ApiFunctionLike, ApiWithInheritance, Api
    * displaying the signature is redundant.
    * Still, if needed, you can use printSignature() util from
    * `@arcgis/api-extractor`.
-   * @example "(options?: __esri.PopupViewOpenPopupOptions): Promise<void>"
+   * @example "(options?: PopupViewOpenPopupOptions): Promise<void>"
    */
   signature: string;
 }
@@ -796,7 +803,7 @@ export interface ApiClassCallSignature extends Omit<ApiFunctionLike, "name">, Ap
 /**
  * A description of a class mixin.
  *
- * @see [WebGIS - Mixins](https://webgis.esri.com/webgis/core/core/mixins)
+ * @see [WebGIS - Mixins](https://webgis.esri.com/sdk/contributing/core/core/mixins)
  */
 export interface ApiMixinDeclaration extends Omit<ApiFunctionLike, "return">, ApiObjectLikeDeclaration, ApiWithEvents {
   kind: "mixin";

package/dist/cli-7PX_wNxb.js

@@ -0,0 +1,34 @@
+import { writeFile as r, readFile as d } from "node:fs/promises";
+import { diffApiJson as m } from "./diff/diffApiJson.js";
+async function k({
+  oldPath: t,
+  newPath: i,
+  outputPath: o,
+  docsUrlPrefix: e
+}) {
+  const c = f(t), w = f(i), p = await c, l = await w, n = m(p, l);
+  if (typeof o == "string")
+    if (o.endsWith(".md")) {
+      const { apiDiffToMarkdown: s } = await import("./diff/apiDiffToMarkdown.js"), a = s(n, e);
+      await r(o, a, "utf-8");
+    } else
+      await r(o, JSON.stringify(n, null, 2), "utf-8");
+  else {
+    const { apiDiffToMarkdown: s } = await import("./diff/apiDiffToMarkdown.js"), a = s(n, e);
+    console.log(a);
+  }
+}
+async function f(t) {
+  if (t.startsWith("http://") || t.startsWith("https://")) {
+    const i = await fetch(t);
+    if (!i.ok)
+      throw new Error(`Failed to fetch api.json: ${i.statusText}`);
+    return await i.json();
+  } else {
+    const i = await d(t, "utf-8");
+    return JSON.parse(i);
+  }
+}
+export {
+  k as diffApiCli
+};

package/dist/cli.js

@@ -1,15 +1,14 @@
-#!/usr/bin/env node
-import { Command as p } from "@commander-js/extra-typings";
-const e = new p();
-e.name("api-extractor").description("Extract public API from a TypeScript project to produce .d.ts types and api.json docs");
-e.command("run").description("Generate .d.ts types and api.json API reference for a project").option("--cwd <arcgis-js-api>", "Path to the root of the project (default: process.cwd())").option("--dts <outputDirectory>", "Destination for the .d.ts files (example: dist/)").option("--api-json <outputLocation>", "Destination for the api.json file (example: dist/docs/api.json)").option("--environment <environment>", "Environment to run in (production or development) (default: production)").option("--type-check", "Run full type checking before the extraction (default: false)").option("--verify", "Run type checker on the emitted types (default: false)").option("--watch", "Watch for file changes and re-run the extraction automatically", !1).option(
+import { Command as c } from "@commander-js/extra-typings";
+const o = new c();
+o.name("api-extractor").description("Extract public API from a TypeScript project to produce .d.ts types and api.json docs");
+o.command("run").description("Generate .d.ts types and api.json API reference for a project").option("--cwd <arcgis-js-api>", "Path to the root of the project (default: process.cwd())").option("--dts <outputDirectory>", "Destination for the .d.ts files (example: dist/)").option("--api-json <outputLocation>", "Destination for the api.json file (example: dist/docs/api.json)").option("--environment <environment>", "Environment to run in (production or development) (default: production)").option("--type-check", "Run full type checking before the extraction (default: false)").option("--verify", "Run type checker on the emitted types (default: false)").option("--watch", "Watch for file changes and re-run the extraction automatically", !1).option(
   "--config <configPath>",
   "Path to the ./api-extractor.config.ts file. The provided path will be used as is in import(). The config file should export a `config` object of type ApiExtractorConfig (default: api-extractor.config.ts in the cwd)"
 ).option(
   "--silence-broken-links",
   "(deprecated) Do not emit errors for broken @links in JSDoc comments. Temporary option for migration period (default: false)"
 ).action(async (t) => {
-  const { loadApiExtractorConfig: o, mergeApiExtractorConfigs: n } = await import("./extractor/config.js"), a = await o(t.cwd, t.config), r = n(a, {
+  const { loadApiExtractorConfig: e, mergeApiExtractorConfigs: n } = await import("./extractor/config.js"), a = await e(t.cwd, t.config), r = n(a, {
     context: {
       dtsEmitPath: t.dts,
       apiJsonEmitPath: t.apiJson,
@@ -23,16 +22,35 @@ e.command("run").description("Generate .d.ts types and api.json API reference fo
       typeCheckTypes: t.verify,
       detectBrokenLinks: t.silenceBrokenLinks === !0 ? !1 : void 0
     }
-  }), { ApiExtractor: c } = await import("./extractor/ApiExtractor.js"), i = new c(r);
+  }), { ApiExtractor: p } = await import("./extractor/ApiExtractor.js"), i = new p(r);
   t.watch ? await i.watch() : await i.run();
 });
-e.command("diff-types").description("Generate a types diff summary .md file").requiredOption("--original-dts <originalTypings>", "Path to the original types folder").requiredOption("--new-dts <newTypings>", "Path to the new types folder").option("--output-md <outputMd>", "Path to the output markdown file", "types-diff.md").option("--no-truncate", "Do not truncate output if it is longer than 1000 lines", !0).action(async (t) => {
-  const { diffTypes: o } = await import("./diffTypes/index.js");
-  await o({
+o.command("diff").description("Produce a diff of two api.json files").requiredOption(
+  "--old <string>",
+  "URL or file path to the old api.json file. Example: https://unpkg.com/@arcgis/map-components@latest/dist/docs/api.json"
+).requiredOption(
+  "--new <string>",
+  "URL or file path to the new api.json file. Example: ./packages/map-packages/map-components/dist/docs/api.json"
+).option("--output <path>", "Path to the output .md or .json file. If not provided, will print markdown to console").option(
+  "--docs-url-prefix <string>",
+  "Base URL for documentation links. Used only if output format is Markdown",
+  "https://developers.arcgis.com/javascript/latest/references/core/"
+).action(async (t) => {
+  const { diffApiCli: e } = await import("./cli-7PX_wNxb.js");
+  await e({
+    oldPath: t.old,
+    newPath: t.new,
+    outputPath: t.output,
+    docsUrlPrefix: t.docsUrlPrefix
+  });
+});
+o.command("diff-types").description("Generate a types diff summary .md file").requiredOption("--original-dts <originalTypings>", "Path to the original types folder").requiredOption("--new-dts <newTypings>", "Path to the new types folder").option("--output-md <outputMd>", "Path to the output markdown file", "types-diff.md").option("--no-truncate", "Do not truncate output if it is longer than 1000 lines", !0).action(async (t) => {
+  const { diffTypes: e } = await import("./diffTypes/index.js");
+  await e({
     originalDtsPath: t.originalDts,
     newDtsPath: t.newDts,
     outputMdPath: t.outputMd,
     truncate: t.truncate
   });
 });
-e.parse();
+o.parse();

package/dist/diff/apiDiffToMarkdown.d.ts

@@ -0,0 +1,9 @@
+import type { ApiDiff } from "./types.js";
+
+/**
+ * Render an ApiDiff to a markdown nested lists tree.
+ *
+ * @param apiJson
+ * @param docsUrlPrefix
+ */
+export function apiDiffToMarkdown(apiJson: Pick<ApiDiff, "modules">, docsUrlPrefix: string): string;

package/dist/diff/apiDiffToMarkdown.js

@@ -0,0 +1,140 @@
+import { buildViewUrl as T } from "../extractor/processing/links.js";
+function K({ modules: e }, t) {
+  const o = {
+    children: /* @__PURE__ */ new Map(),
+    members: []
+  };
+  for (let n = 0; n < e.length; ++n) {
+    const i = e[n], w = i.path.split("/");
+    let y = w;
+    const M = w.at(-1);
+    i.declarations.length === 1 && i.declarations[0].name === M && (y = w.slice(0, -1));
+    let U = o;
+    for (const g of y)
+      U = D(U, g);
+    for (let g = 0; g < i.declarations.length; ++g) {
+      const f = i.declarations[g], S = B(f), O = f.removed === !0 ? void 0 : $(t, i.path, f, void 0), C = j(f), N = { label: S, viewUrl: O, change: C }, d = f, h = [];
+      if (d.members !== void 0)
+        for (let l = 0; l < d.members.length; ++l) {
+          const r = d.members[l], m = r.kind === "field" ? "property" : r.kind === "call-signature" ? "call signature" : r.kind, p = v(m, r);
+          if (p === void 0)
+            continue;
+          const s = F(r), a = r.removed === !0 ? void 0 : $(
+            t,
+            i.path,
+            f,
+            "name" in r ? r.name : `${f.name}Properties`
+          );
+          h.push({ label: s, viewUrl: a, change: p });
+        }
+      if (d.events !== void 0)
+        for (let l = 0; l < d.events.length; ++l) {
+          const r = d.events[l], m = v("event", r);
+          if (m === void 0)
+            continue;
+          const p = r.removed === !0 ? void 0 : $(t, i.path, f, `event-${r.name}`);
+          h.push({ label: `@${r.name}`, viewUrl: p, change: m });
+        }
+      if (typeof d.tagName == "string") {
+        const l = d.slots, r = d.cssParts, m = d.cssProperties, p = d.cssStates;
+        if (l !== void 0)
+          for (let s = 0; s < l.length; ++s) {
+            const a = l[s], u = v("slot", a);
+            if (u === void 0)
+              continue;
+            const b = a.removed === !0 ? void 0 : $(t, i.path, f, `slot-${a.name}`);
+            h.push({ label: a.name, viewUrl: b, change: u });
+          }
+        if (r !== void 0)
+          for (let s = 0; s < r.length; ++s) {
+            const a = r[s], u = v("css part", a);
+            if (u === void 0)
+              continue;
+            h.push({ label: a.name, viewUrl: void 0, change: u });
+          }
+        if (m !== void 0)
+          for (let s = 0; s < m.length; ++s) {
+            const a = m[s], u = v("css property", a);
+            if (u === void 0)
+              continue;
+            const b = a.removed === !0 ? void 0 : $(t, i.path, f, a.name);
+            h.push({ label: a.name, viewUrl: b, change: u });
+          }
+        if (p !== void 0)
+          for (let s = 0; s < p.length; ++s) {
+            const a = p[s], u = v("css state", a);
+            if (u === void 0)
+              continue;
+            h.push({ label: a.name, viewUrl: void 0, change: u });
+          }
+      }
+      h.length > 0 ? E(U, N).members.push(...h) : C !== void 0 && U.members.push(N);
+    }
+  }
+  const c = [];
+  for (const n of o.children.values())
+    L(n, "", c);
+  return c.join(`
+`);
+}
+function D(e, t) {
+  const o = e.children.get(t);
+  if (o !== void 0)
+    return o;
+  const c = { name: t, children: /* @__PURE__ */ new Map(), members: [], node: void 0 };
+  return e.children.set(t, c), c;
+}
+function j(e) {
+  const t = e.tagName !== void 0 ? "component" : e.kind === "interface" ? "type declaration" : e.kind;
+  return v(t, e);
+}
+function v(e, t) {
+  const { added: o, removed: c, deprecated: n } = t;
+  if (c) {
+    const i = `**removed** ${e}`;
+    return typeof n == "string" ? `${i} - deprecated ${x(n)}` : i;
+  }
+  if (n)
+    return typeof n == "string" ? `**deprecated** ${e} ${x(n)}` : `**deprecated** ${e}`;
+  if (o)
+    return `**added** ${e}`;
+}
+function B(e) {
+  const t = e.tagName;
+  return typeof t == "string" && t.length > 0 ? t : k(e.name) + (e.kind === "function" ? "()" : "");
+}
+function $(e, t, o, c) {
+  const n = `${e}${t}/`;
+  return T(n, o.kind === "class" ? void 0 : o.name, c);
+}
+function E(e, t) {
+  const o = D(e, t.label);
+  return o.node = t, o;
+}
+function F(e) {
+  return e.kind === "constructor" ? "constructor" : e.kind === "call-signature" ? "call signature" : e.kind === "method" ? `${k(e.name)}()` : k(e.name);
+}
+function k(e) {
+  return e.replace(/[\\\[\]\(\)]/gu, "\\$&");
+}
+function x(e) {
+  return e.split(`
+`)[0];
+}
+function L(e, t, o) {
+  if (e.node) {
+    const n = e.node.viewUrl === void 0 ? e.node.label : `[${e.node.label}](${e.node.viewUrl})`;
+    e.node.change ? o.push(`${t}- ${n} - ${e.node.change}`) : o.push(`${t}- ${n}`);
+  } else
+    o.push(`${t}- ${e.name}/`);
+  const c = `${t}  `;
+  for (const n of e.members) {
+    const i = n.viewUrl === void 0 ? n.label : `[${n.label}](${n.viewUrl})`;
+    n.change ? o.push(`${c}- ${i} - ${n.change}`) : o.push(`${c}- ${i}`);
+  }
+  for (const n of e.children.values())
+    L(n, c, o);
+}
+export {
+  K as apiDiffToMarkdown
+};

package/dist/diff/diffApiJson.d.ts

@@ -1,4 +1,4 @@
-import type { ApiJson } from "../apiJson.js";
+import type { ApiJson, ApiJsonCompiler } from "../apiJson.js";
 import type { ApiDiff } from "./types.js";
 
 /**
@@ -6,8 +6,8 @@ import type { ApiDiff } from "./types.js";
  * @param newApiJson
  * @example
  * ```js
- * import { diffApiJson, fetchApiJsonFromNpm } from "@arcgis/api-extractor/diff";
- * import { readFileSync, writeFileSync } from "node:fs";
+ * import { diffApiJson } from "@arcgis/api-extractor/diff/diffApiJson";
+ * import { fetchApiJsonFromNpm } from "@arcgis/api-extractor/diff/fetchApiJsonFromNpm";
  *
  * // Read -next api.json from file system:
  * const apiJson = JSON.parse(
@@ -23,4 +23,4 @@ import type { ApiDiff } from "./types.js";
  * writeFileSync("api-diff.json", JSON.stringify(diff, null, 2));
  * ```
  */
-export function diffApiJson(oldApiJson: Pick<ApiJson, "modules">, newApiJson: Pick<ApiJson, "modules">): ApiDiff;
+export function diffApiJson(oldApiJson: Pick<ApiJson, "modules"> & { compiler?: ApiJsonCompiler; }, newApiJson: Pick<ApiJson, "modules"> & { compiler?: ApiJsonCompiler; }): ApiDiff;