@aurodesignsystem/auro-library 5.13.2 → 5.14.0

package/.tool-versions

@@ -1 +1 @@
-nodejs 20.12.1
+nodejs 22.22.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Semantic Release Automated Changelog
 
+# [5.14.0](https://github.com/AlaskaAirlines/auro-library/compare/v5.13.3...v5.14.0) (2026-08-30)
+
+
+### Features
+
+* add shared deprecatedProseToFieldPlugin CEM build utility AB[#1633054](https://github.com/AlaskaAirlines/auro-library/issues/1633054) ([0230385](https://github.com/AlaskaAirlines/auro-library/commit/0230385fb7870411e00b05b8dc18204ce70e4e2f))
+
+## [5.13.3](https://github.com/AlaskaAirlines/auro-library/compare/v5.13.2...v5.13.3) (2026-08-07)
+
+
+### Bug Fixes
+
+* **floatingUI:** suppress Escape keydown for modal dialogs to prevent CloseWatcher force-close AB[#1613688](https://github.com/AlaskaAirlines/auro-library/issues/1613688) ([efd81c5](https://github.com/AlaskaAirlines/auro-library/commit/efd81c5fd96f4d02253e4ce76b4e7a2ddb8d25c7))
+
 ## [5.13.2](https://github.com/AlaskaAirlines/auro-library/compare/v5.13.1...v5.13.2) (2026-07-28)
 
 

package/README.md

@@ -233,3 +233,35 @@ To run the `generateWcaComponent.mjs` script, you need to provide the file paths
 "build:api:prepare": "node ./node_modules/@aurodesignsystem/auro-library/scripts/config/syncAllTemplates.mjs 'src/auro-flight*.js'"
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
+
+---
+
+### Deprecation Prose to CEM Field Plugin
+
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/deprecatedProseToFieldPlugin.md) -->
+<!-- The below content is automatically added from ./../docs/partials/deprecatedProseToFieldPlugin.md -->
+The `deprecatedProseToFieldPlugin` is a shared [Custom Elements Manifest](https://github.com/open-wc/custom-elements-manifest) analyzer plugin. It promotes deprecation prose written on `@event` and `@slot` tags into the machine-readable `deprecated` field of the generated `custom-elements.json`, so editor tooling can strike deprecated events and slots through.
+
+The CEM analyzer already emits a `deprecated` field for attributes and members declared with an explicit `@deprecated` JSDoc tag, but it does **not** do so for events and slots declared as inline class-level `@event` / `@slot` tags. This plugin fills that gap by scanning each declaration's `events` and `slots` and, where a description contains a deprecation marker (`(Deprecated) …`, `**DEPRECATED** …`, or a leading `deprecated` word):
+
+- sets `deprecated` to the guidance text that follows the marker and a separator (`-`, `:`, `–`, or `—`) — for example, `"Use the \`input\` event instead."`, or
+- sets `deprecated` to `true` when the prose offers no replacement guidance.
+
+Attributes and members are intentionally left untouched — the analyzer already flags those correctly. Entries that already carry a `deprecated` value are never overwritten.
+
+## Usage
+
+Import the plugin into your component library's `custom-elements-manifest.config.mjs` and add it to the `plugins` array:
+
+```js
+import { deprecatedProseToFieldPlugin } from '@aurodesignsystem/auro-library/scripts/build/deprecatedProseToFieldPlugin.mjs';
+
+export default {
+  globs: ['components/**/src/*.js'],
+  litelement: true,
+  plugins: [deprecatedProseToFieldPlugin()]
+};
+```
+
+Regenerating your `custom-elements.json` will now mark deprecated events and slots with their guidance messages.
+<!-- AURO-GENERATED-CONTENT:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurodesignsystem/auro-library",
-  "version": "5.13.2",
+  "version": "5.14.0",
   "description": "This repository holds shared scripts, utilities, and workflows utilized across repositories along the Auro Design System.",
   "repository": {
     "type": "git",
@@ -27,10 +27,10 @@
     "@open-wc/testing": "^4.0.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/npm": "^11.0.2",
+    "@semantic-release/npm": "^13.0.0",
     "husky": "^9.1.7",
     "npm-run-all": "^4.1.5",
-    "semantic-release": "^23.0.0",
+    "semantic-release": "^25.0.0",
     "sinon": "^20.0.0",
     "vitest": "^2.1.2"
   },
@@ -70,7 +70,8 @@
     ]
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "scripts": {
     "prepare": "husky install",

package/scripts/build/deprecatedProseToFieldPlugin.mjs

@@ -0,0 +1,66 @@
+/**
+ * Promote deprecation prose on events and slots into the CEM `deprecated` field.
+ *
+ * The analyzer (v0.11.0) emits a `deprecated` field for attributes and members
+ * from an explicit `@deprecated` JSDoc tag, but it does NOT do so for events and
+ * slots declared as inline class-level `@event` / `@slot` tags — so an event or
+ * slot whose description reads as deprecated ("(Deprecated) …", "**DEPRECATED** …")
+ * carries no machine-readable flag, and editor tooling cannot strike it through.
+ *
+ * This post-processing plugin scans each declaration's `events` and `slots`, and
+ * where the description contains a deprecation marker, sets `deprecated` to the
+ * guidance text following the marker (e.g. "Use `x` instead.") or `true` when the
+ * prose offers no replacement guidance. Attributes and members are intentionally
+ * left untouched — the analyzer already flags those correctly.
+ *
+ * Shared build utility for the Auro Design System. Import it into a component
+ * library's `custom-elements-manifest.config.mjs`:
+ *
+ * ```js
+ * import { deprecatedProseToFieldPlugin } from '@aurodesignsystem/auro-library/scripts/build/deprecatedProseToFieldPlugin.mjs';
+ *
+ * export default {
+ *   // …
+ *   plugins: [deprecatedProseToFieldPlugin()]
+ * };
+ * ```
+ *
+ * @returns {{ name: string, packageLinkPhase: (context: { customElementsManifest: object }) => void }}
+ *   A Custom Elements Manifest analyzer plugin.
+ */
+export function deprecatedProseToFieldPlugin() {
+  const MARKER = /\*\*deprecated\*\*|\(deprecated\)|(?:^|\s)deprecated\b/i;
+  const GUIDANCE =
+    /(?:\*\*deprecated\*\*|\(deprecated\)|(?:^|\s)deprecated\b)\s*[-:–—]\s*(.+)/is;
+
+  const promote = (entries) => {
+    if (!Array.isArray(entries)) {
+      return;
+    }
+    for (const entry of entries) {
+      if (
+        entry.deprecated !== undefined ||
+        typeof entry.description !== "string"
+      ) {
+        continue;
+      }
+      if (!MARKER.test(entry.description)) {
+        continue;
+      }
+      const guidance = entry.description.match(GUIDANCE);
+      entry.deprecated = guidance && guidance[1] ? guidance[1].trim() : true;
+    }
+  };
+
+  return {
+    name: "deprecated-prose-to-field",
+    packageLinkPhase({ customElementsManifest }) {
+      for (const mod of customElementsManifest.modules ?? []) {
+        for (const declaration of mod.declarations ?? []) {
+          promote(declaration.events);
+          promote(declaration.slots);
+        }
+      }
+    },
+  };
+}

package/scripts/build/deprecatedProseToFieldPlugin.spec.js

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "vitest";
+import { deprecatedProseToFieldPlugin } from "./deprecatedProseToFieldPlugin.mjs";
+
+/**
+ * Wrap one or more `entries` (events or slots) in a minimal Custom Elements
+ * Manifest shape, run the plugin's `packageLinkPhase` over it, and return the
+ * mutated entries so assertions can read their `deprecated` field.
+ */
+const run = (kind, entries) => {
+  const manifest = {
+    modules: [
+      {
+        declarations: [{ [kind]: entries }],
+      },
+    ],
+  };
+  deprecatedProseToFieldPlugin().packageLinkPhase({
+    customElementsManifest: manifest,
+  });
+  return manifest.modules[0].declarations[0][kind];
+};
+
+describe("deprecatedProseToFieldPlugin", () => {
+  it("has the expected plugin name", () => {
+    expect(deprecatedProseToFieldPlugin().name).toBe(
+      "deprecated-prose-to-field",
+    );
+  });
+
+  describe("marker + guidance -> string message", () => {
+    it('extracts guidance following a "(deprecated) -" marker', () => {
+      const [entry] = run("events", [
+        {
+          name: "change",
+          description: "(Deprecated) - Use the `input` event instead.",
+        },
+      ]);
+      expect(entry.deprecated).toBe("Use the `input` event instead.");
+    });
+
+    it("extracts guidance for each supported separator (- : – —)", () => {
+      const separators = ["-", ":", "–", "—"];
+      separators.forEach((sep) => {
+        const [entry] = run("events", [
+          {
+            name: "change",
+            description: `**DEPRECATED** ${sep} Use \`input\` instead.`,
+          },
+        ]);
+        expect(entry.deprecated).toBe("Use `input` instead.");
+      });
+    });
+
+    it("trims surrounding whitespace from the guidance text", () => {
+      const [entry] = run("slots", [
+        {
+          name: "legacy",
+          description: "deprecated:   Use the `default` slot instead.   ",
+        },
+      ]);
+      expect(entry.deprecated).toBe("Use the `default` slot instead.");
+    });
+  });
+
+  describe("marker with no guidance -> boolean true", () => {
+    it('flags a "**DEPRECATED**" prose with no replacement guidance', () => {
+      const [entry] = run("slots", [
+        { name: "legacy", description: "**DEPRECATED** legacy slot" },
+      ]);
+      expect(entry.deprecated).toBe(true);
+    });
+
+    it('flags a bare "(deprecated)" marker as true', () => {
+      const [entry] = run("events", [
+        { name: "change", description: "(deprecated)" },
+      ]);
+      expect(entry.deprecated).toBe(true);
+    });
+  });
+
+  describe("non-deprecated entries are untouched", () => {
+    it("does not add a deprecated field when no marker is present", () => {
+      const [entry] = run("events", [
+        { name: "input", description: "Fires when the value changes." },
+      ]);
+      expect(entry).not.toHaveProperty("deprecated");
+    });
+
+    it('does not match unrelated words containing "deprecated" as a substring', () => {
+      const [entry] = run("events", [
+        { name: "input", description: "This is undeprecated behavior." },
+      ]);
+      expect(entry).not.toHaveProperty("deprecated");
+    });
+  });
+
+  describe("pre-existing deprecated values are preserved", () => {
+    it("does not overwrite an already-set string message", () => {
+      const [entry] = run("events", [
+        {
+          name: "change",
+          description: "(Deprecated) - Use `input`.",
+          deprecated: "existing guidance",
+        },
+      ]);
+      expect(entry.deprecated).toBe("existing guidance");
+    });
+
+    it("does not overwrite an already-set boolean false", () => {
+      const [entry] = run("events", [
+        {
+          name: "change",
+          description: "(Deprecated) - Use `input`.",
+          deprecated: false,
+        },
+      ]);
+      expect(entry.deprecated).toBe(false);
+    });
+  });
+
+  describe("malformed / missing descriptions are skipped safely", () => {
+    it("skips entries whose description is not a string", () => {
+      const [noDesc, objDesc] = run("slots", [
+        { name: "a" },
+        { name: "b", description: { text: "deprecated" } },
+      ]);
+      expect(noDesc).not.toHaveProperty("deprecated");
+      expect(objDesc).not.toHaveProperty("deprecated");
+    });
+  });
+
+  describe("applies to both events and slots, leaves other fields alone", () => {
+    it("promotes both events and slots on the same declaration", () => {
+      const manifest = {
+        modules: [
+          {
+            declarations: [
+              {
+                events: [
+                  { name: "change", description: "deprecated - Use `input`." },
+                ],
+                slots: [
+                  { name: "legacy", description: "(Deprecated) legacy slot" },
+                ],
+                attributes: [
+                  {
+                    name: "value",
+                    description: "deprecated - do not touch me",
+                  },
+                ],
+                members: [
+                  { name: "reset", description: "(deprecated) leave me alone" },
+                ],
+              },
+            ],
+          },
+        ],
+      };
+      deprecatedProseToFieldPlugin().packageLinkPhase({
+        customElementsManifest: manifest,
+      });
+      const [decl] = manifest.modules[0].declarations;
+      expect(decl.events[0].deprecated).toBe("Use `input`.");
+      expect(decl.slots[0].deprecated).toBe(true);
+      expect(decl.attributes[0]).not.toHaveProperty("deprecated");
+      expect(decl.members[0]).not.toHaveProperty("deprecated");
+    });
+  });
+
+  describe("does not throw on empty or absent manifest structures", () => {
+    it("handles a manifest with no modules", () => {
+      expect(() =>
+        deprecatedProseToFieldPlugin().packageLinkPhase({
+          customElementsManifest: {},
+        }),
+      ).not.toThrow();
+    });
+
+    it("handles declarations without events or slots arrays", () => {
+      const manifest = { modules: [{ declarations: [{}] }] };
+      expect(() =>
+        deprecatedProseToFieldPlugin().packageLinkPhase({
+          customElementsManifest: manifest,
+        }),
+      ).not.toThrow();
+    });
+  });
+});

package/scripts/runtime/floatingUI.mjs

@@ -778,6 +778,24 @@ export default class AuroFloatingUI {
       if (!this.showing) {
         if (!element.modal) {
           this.setupHideHandlers();
+        } else {
+          if (this.keyDownHandler) {
+            document.removeEventListener("keydown", this.keyDownHandler);
+          }
+          this.keyDownHandler = (evt) => {
+            if (evt.key === "Escape" && element.isPopoverVisible) {
+              // Intercept at keydown so CloseWatcher never sees the keystroke.
+              // Canceling `cancel` alone is insufficient — a second Esc with no
+              // intervening user activation triggers the anti-trap and fires `close`
+              // directly, bypassing any `cancel` preventDefault (AB#1613688).
+              // stopImmediatePropagation is intentional: it prevents other document
+              // keydown handlers (e.g. consumer code, auro-dialog) from also acting
+              // on Escape while the modal owns the key.
+              evt.preventDefault();
+              evt.stopImmediatePropagation();
+            }
+          };
+          document.addEventListener("keydown", this.keyDownHandler);
         }
         this.showing = true;
         element.isPopoverVisible = true;

package/scripts/runtime/floatingUI.test.js

@@ -295,6 +295,85 @@ describe("AuroFloatingUI", () => {
   });
 });
 
+describe("AuroFloatingUI modal Escape suppression (AB#1613688)", () => {
+  let host;
+  let bib;
+  let floatingUI;
+  let hideBibSpy;
+
+  beforeEach(() => {
+    host = document.createElement("div");
+    bib = document.createElement("div");
+    host.bib = bib;
+    host.modal = true;
+    host.isPopoverVisible = false;
+    host.triggerChevron = document.createElement("span");
+    document.body.append(host, bib);
+
+    AuroFloatingUI.openingQueue = [];
+    document.expandedAuroFloater = null;
+
+    floatingUI = new AuroFloatingUI(host, "dialog");
+    hideBibSpy = sinon.spy(floatingUI, "hideBib");
+  });
+
+  afterEach(() => {
+    floatingUI.cleanupHideHandlers();
+    sinon.restore();
+    AuroFloatingUI.isMousePressed = false;
+    AuroFloatingUI.openingQueue = [];
+    document.expandedAuroFloater = null;
+    host?.remove();
+    bib?.remove();
+  });
+
+  it("registers a keydown handler and skips setupHideHandlers when modal=true", () => {
+    const setupHideHandlersSpy = sinon.spy(floatingUI, "setupHideHandlers");
+
+    floatingUI.showBib();
+
+    expect(setupHideHandlersSpy.called).to.be.false;
+    expect(floatingUI.keyDownHandler).to.be.a("function");
+    expect(floatingUI.showing).to.be.true;
+  });
+
+  it("does not call hideBib when Escape is pressed while modal dialog is open", () => {
+    floatingUI.showBib();
+
+    document.dispatchEvent(
+      new KeyboardEvent("keydown", {
+        key: "Escape",
+        bubbles: true,
+        cancelable: true,
+      }),
+    );
+
+    expect(hideBibSpy.called).to.be.false;
+  });
+
+  it("calls preventDefault on Escape keydown while modal dialog is open", () => {
+    floatingUI.showBib();
+
+    const escEvent = new KeyboardEvent("keydown", {
+      key: "Escape",
+      bubbles: true,
+      cancelable: true,
+    });
+    const preventDefaultSpy = sinon.spy(escEvent, "preventDefault");
+    document.dispatchEvent(escEvent);
+
+    expect(preventDefaultSpy.calledOnce).to.be.true;
+  });
+
+  it("removes the modal Escape keydown handler via cleanupHideHandlers", () => {
+    floatingUI.showBib();
+    expect(floatingUI.keyDownHandler).to.be.a("function");
+
+    floatingUI.cleanupHideHandlers();
+    expect(floatingUI.keyDownHandler).to.be.null;
+  });
+});
+
 describe("AuroFloatingUI.openingQueue and topOpeningFloatingUI", () => {
   let floatingUI1;
   let floatingUI2;