@antglobal/copilot-cards-web 1.0.7 → 1.0.9

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.8
 ```
 
 `@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.
@@ -69,10 +113,44 @@ Renders a complete schema and returns a `CardInstance`:
 ```ts
 interface CardInstance {
   updateVariables(variables: Record<string, unknown>): void;
+  onScroll(nodeId: string, listener: CardScrollListener): () => void;
   dispose(): void;
 }
 ```
 
+`CardScrollEvent` and `CardScrollListener` are top-level package exports. The
+event contains readonly `node`, `scrollTop`, `scrollLeft`, `scrollHeight`,
+`scrollWidth`, `clientHeight`, and `clientWidth` values:
+
+```ts
+import type {
+  CardScrollEvent,
+  CardScrollListener,
+} from "@antglobal/copilot-cards-web";
+
+const unsubscribe = card.onScroll("friendsList", event => {
+  const remaining =
+    event.scrollHeight - event.clientHeight - event.scrollTop;
+});
+
+unsubscribe(); // Idempotent; card.dispose() also removes the subscription.
+```
+
+The subscription follows the logical node ID across physical replacement and
+reports native-frequency values. It does not emit an initial, render, resize,
+or `updateVariables` callback. Generated internal scroll tracks and scroll
+ports inside Shadow DOM are not observed. Thresholds, throttling, requests,
+locks, cursors, retries, and deduplication remain host responsibilities.
+
+For pagination, continue passing the complete next array to `updateVariables`.
+The SDK retains the Repeat owner and old prefix only when it can strictly prove
+a structurally equal tail extension whose retained rendering is unchanged, on
+a default-rendered `Container` with an unambiguous direct-child `default` or
+`flex` layout. Every unproven case uses the existing replacement behavior; this
+is not a general keyed diff or public append API. A trailing control object is
+eligible only when it does not change retained rows. Put temporary loading UI
+outside the Repeat owner when scroll identity matters.
+
 Common render options include:
 
 | Option | Purpose |

package/dist/index.d.ts

@@ -55,6 +55,23 @@ interface CardFocusChangeEvent {
     previousNode: CardNodeHandle | null;
 }
 type CardFocusChangeListener = (event: CardFocusChangeEvent) => void;
+interface CardScrollEvent {
+    /** Stable logical handle for the scrolling card node. */
+    readonly node: CardNodeHandle;
+    /** Raw native vertical scroll offset. */
+    readonly scrollTop: number;
+    /** Raw native horizontal scroll offset, including negative RTL values. */
+    readonly scrollLeft: number;
+    /** Raw native scrollable content height. */
+    readonly scrollHeight: number;
+    /** Raw native scrollable content width. */
+    readonly scrollWidth: number;
+    /** Raw native viewport height. */
+    readonly clientHeight: number;
+    /** Raw native viewport width. */
+    readonly clientWidth: number;
+}
+type CardScrollListener = (event: CardScrollEvent) => void;
 
 interface ResponsiveMobileOptions {
     readonly unit: 'rem';
@@ -108,6 +125,8 @@ interface CardInstance {
     getNode: (id: string) => CardNodeHandle;
     /** Observe logical focus changes within this card. */
     onFocusChange: (listener: CardFocusChangeListener) => () => void;
+    /** Observe native scroll metrics for one logical card node. */
+    onScroll: (nodeId: string, listener: CardScrollListener) => () => void;
 }
 /**
  * Render a card schema into a container element.
@@ -707,6 +726,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;
@@ -1837,4 +1860,4 @@ declare const componentRenderers: Record<string, ComponentRenderer>;
 declare function registerComponent(type: string, renderer: ComponentRenderer): void;
 
 export { BaseElement, BotSDK, CardButton, CardChoiceItem, CardChoiceList, CardCollapse, CardCounter, CardDivider, CardForm, CardHtml, CardIcon, CardImage, CardInput, CardLoading, CardPasscodeInput, CardProgress, CardRate, CardSelect, CardSteps, CardSwitch, CardTag, CardText, DEFAULT_MOBILE_RESPONSIVE, LocalActionConfigProvider, RemoteActionConfigProvider, buildStyleString, componentRenderers, connectSSE, connectStreaming, convertPixelTokens, createResponsiveContext, createWebActionContext, isMobileViewport, onViewportChange, pxToRem, pxToVw, registerComponent, renderCard, renderStreamingCard, resolveSize, sanitizeHtml, trimIncompleteTag };
-export type { A2UIActionPayload, BotSDKOptions, ButtonProps, CardFocusChangeEvent, CardFocusChangeListener, CardInstance, CardNodeHandle, ChoiceIndicatorIcon, ChoiceItemProps, ChoiceListProps, ChoiceListValue, CollapseProps, ComponentRenderer, ConnectorConfig, CounterIcon, CounterProps, DividerProps, FormField, FormProps, FormRule, HtmlProps, IconProps, ImageProps, InputAffix, InputAffixConfig, InputProps, LoadingProps, PartialFinalizeResult, PasscodeInputProps, ProgressProps, ProgressSegment, RateProps, RenderCardOptions, ResponsiveContext, ResponsiveMobileOptions, ResponsiveOptions, SSEConnectOptions, SelectOption, SelectProps, SelectSize, SelectStyles, SelectVariant, StepIcon, StepItem, StepsProps, StreamingCardInstance, StreamingCardOptions, StreamingConnectOptions, StreamingConnection, SwitchProps, TagProps, TextProps, WebActionContextOptions };
+export type { A2UIActionPayload, BotSDKOptions, ButtonProps, CardFocusChangeEvent, CardFocusChangeListener, CardInstance, CardNodeHandle, CardScrollEvent, CardScrollListener, ChoiceIndicatorIcon, ChoiceItemProps, ChoiceListProps, ChoiceListValue, CollapseProps, ComponentRenderer, ConnectorConfig, CounterIcon, CounterProps, DividerProps, FormField, FormProps, FormRule, HtmlProps, IconProps, ImageProps, InputAffix, InputAffixConfig, InputProps, LoadingProps, PartialFinalizeResult, PasscodeInputProps, ProgressProps, ProgressSegment, RateProps, RenderCardOptions, ResponsiveContext, ResponsiveMobileOptions, ResponsiveOptions, SSEConnectOptions, SelectOption, SelectProps, SelectSize, SelectStyles, SelectVariant, StepIcon, StepItem, StepsProps, StreamingCardInstance, StreamingCardOptions, StreamingConnectOptions, StreamingConnection, SwitchProps, TagProps, TextProps, WebActionContextOptions };