@antglobal/copilot-cards-web 1.0.6 → 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

@@ -29,6 +29,33 @@ interface WebActionContextOptions {
  */
 declare function createWebActionContext(options?: WebActionContextOptions): ActionRunnerContext;
 
+interface CardNodeHandle {
+    /** Stable schema/runtime node id represented by this logical handle. */
+    readonly id: string;
+    /** Current rendered node type, or null while the node is unavailable. */
+    readonly type: string | null;
+    /**
+     * Current custom-element host. This is a transient snapshot and may change
+     * after any render; consumers should keep the handle instead of this value.
+     */
+    readonly current: HTMLElement | null;
+    /** Measure the current custom-element host. */
+    getRect(): DOMRectReadOnly | null;
+    /** Focus the component's logical control. */
+    focus(options?: FocusOptions): boolean;
+    /** Blur the component's logical control. */
+    blur(): boolean;
+    /** Scroll the current custom-element host into view. */
+    scrollIntoView(options?: ScrollIntoViewOptions): boolean;
+}
+interface CardFocusChangeEvent {
+    /** Currently focused logical card node, or null after focus leaves the card. */
+    node: CardNodeHandle | null;
+    /** Previously focused logical card node, if any. */
+    previousNode: CardNodeHandle | null;
+}
+type CardFocusChangeListener = (event: CardFocusChangeEvent) => void;
+
 interface ResponsiveMobileOptions {
     readonly unit: 'rem';
     readonly rootValue: number;
@@ -77,6 +104,10 @@ interface CardInstance {
     dispose: () => void;
     /** Update variables and re-render. */
     updateVariables: (variables: Record<string, any>) => void;
+    /** Get a stable logical handle that resolves the current host lazily. */
+    getNode: (id: string) => CardNodeHandle;
+    /** Observe logical focus changes within this card. */
+    onFocusChange: (listener: CardFocusChangeListener) => () => void;
 }
 /**
  * Render a card schema into a container element.
@@ -470,6 +501,18 @@ declare abstract class BaseElement extends HTMLElement {
     protected toCSS(value: string | number): string;
     /** Assign component markup and convert only its CSS declarations. */
     protected setShadowHTML(html: string): void;
+    /**
+     * Patch freshly rendered markup around an existing interactive element.
+     *
+     * Replacing a focused native control through `shadowRoot.innerHTML` resets
+     * its selection and, on mobile WebViews, can also recreate the soft
+     * keyboard with a different layout. This helper keeps the selected element
+     * connected while reconciling its surrounding markup.
+     */
+    protected patchShadowHTMLPreservingElement(html: string, preserved: Element, selector: string): boolean;
+    private reconcilePreservedTree;
+    private patchPreservedElement;
+    private reconcileKey;
     /**
      * Escape a value before interpolating it into a double-quoted HTML
      * attribute. Browsers decode the entities before parsing inline CSS, so
@@ -620,9 +663,14 @@ declare class CardButton extends BaseElement {
 
 declare class CardInput extends BaseElement {
     static readonly is = "ai-card-input";
+    private readonly wiredInputs;
+    private readonly wiredNumberInputs;
     protected render(): void;
-    private getAutoFocusControl;
-    private isFirstAvailableAutoFocusInput;
+    /**
+     * Consume an interaction-driven focus request from the card renderer.
+     * Mounts and ordinary updates never call this method.
+     */
+    requestAutoFocus(): boolean;
     /** Escape HTML entities for safe insertion. */
     private escapeHtml;
     /** Escape attribute values for safe insertion. */
@@ -659,7 +707,13 @@ 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;
     private bindEvents;
     private openLightbox;
     private closeLightbox;
@@ -1020,10 +1074,12 @@ type InputAffix = string | InputAffixConfig;
 interface InputProps {
     /** Placeholder text */
     placeholder?: string;
-    /** Focus the native input after the component is mounted (default false) */
+    /** Focus an empty input when a card interaction reveals it (default false) */
     autoFocus?: boolean;
     /** HTML input type: text / textarea / password / number etc. */
     inputType?: 'text' | 'textarea' | 'password' | (string & {});
+    /** Mobile soft-keyboard hint; does not change validation or step controls. */
+    inputMode?: 'none' | 'text' | 'tel' | 'url' | 'email' | 'numeric' | 'decimal' | 'search';
     /** Label text displayed above the input */
     label?: string;
     /** Initial value */
@@ -1061,9 +1117,9 @@ interface ImageProps {
     /** Alt text for accessibility */
     alt?: string;
     /** Image width (CSS value) */
-    width?: string;
+    width?: string | number;
     /** Image height (CSS value) */
-    height?: string;
+    height?: string | number;
     /** CSS object-fit mode (default 'cover') */
     objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
     /** Whether lightbox preview is enabled (default true) */
@@ -1785,4 +1841,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, CardInstance, 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, 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 };