@antglobal/copilot-cards-web 1.0.8 → 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@1.0.7
+npm install @antglobal/copilot-cards-web@1.0.8
 ```
 
 `@antglobal/copilot-cards-core` is installed automatically.
@@ -113,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.
@@ -1841,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 };