@antglobal/copilot-cards-web 1.0.7 → 1.0.8

package/README.md

@@ -7,7 +7,7 @@ The package includes the core schema and action APIs, responsive rendering, Shad
 ## Installation
 
 ```bash
-npm install @antglobal/copilot-cards-web
+npm install @antglobal/copilot-cards-web@1.0.7
 ```
 
 `@antglobal/copilot-cards-core` is installed automatically.
@@ -50,6 +50,50 @@ card.updateVariables({ userName: "Alice" });
 card.dispose();
 ```
 
+## Stable host updates
+
+Create the card once and keep its `CardInstance`. Input events should update
+only the variables that changed. Do not call `renderCard()` again for input updates,
+because remounting the card recreates image elements and can cause visible flicker.
+
+```ts
+import {
+  renderCard,
+  type CardInstance,
+  type CardSchema,
+} from "@antglobal/copilot-cards-web";
+
+let card: CardInstance | null = null;
+
+export function mountDataRechargeCard(
+  container: HTMLElement,
+  schema: CardSchema,
+): void {
+  card?.dispose();
+  card = renderCard(container, schema, {
+    emit: (eventName, payload) => {
+      if (eventName !== "dataRecharge.phone.input") return;
+
+      const value = String(
+        (payload as { value?: unknown } | undefined)?.value ?? "",
+      );
+      if (!card) return;
+      card.updateVariables({ phoneNumber: value });
+    },
+  });
+}
+
+export function unmountDataRechargeCard(): void {
+  card?.dispose();
+  card = null;
+}
+```
+
+Keep `skuOptions` and `isSkuLoading` out of each keystroke patch unless their
+values actually changed. Fetching or filtering SKU data can run from the
+`dataRecharge.phone.commit` event instead of remounting the card on every
+`dataRecharge.phone.input` event.
+
 ## Framework usage
 
 The renderer accesses browser APIs and should be loaded on the client in frameworks that perform server-side rendering.

package/dist/index.d.ts

@@ -707,6 +707,10 @@ declare class CardInput extends BaseElement {
 declare class CardImage extends BaseElement {
     static readonly is = "ai-card-image";
     private _lightbox;
+    private readonly _wiredImages;
+    private readonly _wiredLightboxes;
+    private readonly _wiredCloseButtons;
+    private readonly _handleEscape;
     protected render(): void;
     private applyHostDimension;
     private resolveDeclaredDimension;

package/dist/index.js

@@ -2464,7 +2464,9 @@ class BaseElement extends HTMLElement {
             }
         }
         for (const attribute of Array.from(desired.attributes)) {
-            current.setAttribute(attribute.name, attribute.value);
+            if (current.getAttribute(attribute.name) !== attribute.value) {
+                current.setAttribute(attribute.name, attribute.value);
+            }
         }
         if (current === preserved)
             return;
@@ -3895,6 +3897,14 @@ class CardImage extends BaseElement {
     constructor() {
         super(...arguments);
         this._lightbox = null;
+        this._wiredImages = new WeakSet();
+        this._wiredLightboxes = new WeakSet();
+        this._wiredCloseButtons = new WeakSet();
+        this._handleEscape = (event) => {
+            if (event.key === 'Escape' && this._lightbox) {
+                this.closeLightbox(this._lightbox);
+            }
+        };
     }
     render() {
         if (!this.shadowRoot || !this._node)
@@ -3935,7 +3945,7 @@ class CardImage extends BaseElement {
             imgStyles.push(`object-fit:${objectFit}`);
         if (inlineStyle)
             imgStyles.push(inlineStyle);
-        this.setShadowHTML(`
+        const markup = `
       <style>
         :host {
           display: inline-block;
@@ -4043,11 +4053,25 @@ class CardImage extends BaseElement {
           loading="lazy"
         />
       </div>
-      <div class="lightbox">
-        <button class="lightbox-close" aria-label="Close">&times;</button>
-        <img class="lightbox-image" src="${imgSrc}" alt="${imgAlt}" />
-      </div>
-    `);
+      ${preview ? `
+        <div class="lightbox">
+          <button class="lightbox-close" aria-label="Close">&times;</button>
+          <img class="lightbox-image" src="${imgSrc}" alt="${imgAlt}" />
+        </div>
+      ` : ''}
+    `;
+        const currentImage = this.shadowRoot.querySelector('.card-image');
+        const keepError = currentImage?.classList.contains('error') === true
+            && currentImage.getAttribute('src') === imgSrc;
+        if (this._lightbox?.classList.contains('open')) {
+            this.closeLightbox(this._lightbox);
+        }
+        if (!currentImage
+            || !this.patchShadowHTMLPreservingElement(markup, currentImage, '.card-image')) {
+            this.setShadowHTML(markup);
+        }
+        if (keepError)
+            currentImage.classList.add('error');
         this.bindEvents(preview);
     }
     applyHostDimension(property, styleValue, propValue) {
@@ -4076,53 +4100,66 @@ class CardImage extends BaseElement {
         const img = this.shadowRoot.querySelector('.card-image');
         const lightbox = this.shadowRoot.querySelector('.lightbox');
         const closeBtn = this.shadowRoot.querySelector('.lightbox-close');
-        if (!img || !lightbox)
+        if (!img)
             return;
         // Handle image load/error states
-        img.addEventListener('load', () => {
-            img.classList.remove('loading');
-        });
-        img.addEventListener('error', () => {
-            img.classList.remove('loading');
-            img.classList.add('error');
-        });
-        if (!preview)
+        if (!this._wiredImages.has(img)) {
+            this._wiredImages.add(img);
+            img.addEventListener('load', () => {
+                img.classList.remove('loading');
+                img.classList.remove('error');
+            });
+            img.addEventListener('error', () => {
+                img.classList.remove('loading');
+                img.classList.add('error');
+            });
+            img.addEventListener('click', (event) => {
+                if (this._props.preview === false)
+                    return;
+                const activeLightbox = this.shadowRoot?.querySelector('.lightbox');
+                if (!activeLightbox)
+                    return;
+                event.stopPropagation();
+                this.openLightbox(activeLightbox);
+            });
+        }
+        if (!preview || !lightbox || !closeBtn) {
+            this._lightbox = null;
             return;
-        // Open lightbox on image click
-        img.addEventListener('click', (e) => {
-            e.stopPropagation();
-            this.openLightbox(lightbox);
-        });
+        }
         // Close lightbox on overlay/close button click
-        lightbox.addEventListener('click', () => {
-            this.closeLightbox(lightbox);
-        });
-        closeBtn.addEventListener('click', (e) => {
-            e.stopPropagation();
-            this.closeLightbox(lightbox);
-        });
+        if (!this._wiredLightboxes.has(lightbox)) {
+            this._wiredLightboxes.add(lightbox);
+            lightbox.addEventListener('click', () => {
+                this.closeLightbox(lightbox);
+            });
+        }
+        if (!this._wiredCloseButtons.has(closeBtn)) {
+            this._wiredCloseButtons.add(closeBtn);
+            closeBtn.addEventListener('click', (event) => {
+                event.stopPropagation();
+                this.closeLightbox(lightbox);
+            });
+        }
         // Close on Escape key
         this._lightbox = lightbox;
     }
     openLightbox(lightbox) {
+        this._lightbox = lightbox;
         lightbox.classList.add('open');
         document.body.style.overflow = 'hidden';
-        // Add escape key listener
-        const handleEscape = (e) => {
-            if (e.key === 'Escape') {
-                this.closeLightbox(lightbox);
-                document.removeEventListener('keydown', handleEscape);
-            }
-        };
-        document.addEventListener('keydown', handleEscape);
+        document.addEventListener('keydown', this._handleEscape);
     }
     closeLightbox(lightbox) {
         lightbox.classList.remove('open');
         document.body.style.overflow = '';
+        document.removeEventListener('keydown', this._handleEscape);
     }
     disconnectedCallback() {
         // Ensure body overflow is restored when element is removed
         document.body.style.overflow = '';
+        document.removeEventListener('keydown', this._handleEscape);
+        this._lightbox = null;
     }
 }
 CardImage.is = 'ai-card-image';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antglobal/copilot-cards-web",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Web Component renderer for copilot bot card SDK — PC + Mobile + WebView unified rendering via Custom Elements",
   "type": "module",
   "module": "./dist/index.js",
@@ -28,7 +28,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@antglobal/copilot-cards-core": "^1.0.5",
+    "@antglobal/copilot-cards-core": "^1.0.8",
     "echarts": "^5.6.0",
     "marked": "^18.0.5",
     "tslib": "^2.8.1",