@antglobal/copilot-cards-web 1.0.3 → 1.0.5

package/README.md

@@ -78,14 +78,19 @@ Common render options include:
 | Option | Purpose |
 | --- | --- |
 | `variables` | Overrides initial schema variables |
-| `botId` | Selects bot-scoped custom action handlers |
-| `isMobile` | Overrides automatic viewport detection |
+| `botId` | Optionally selects bot-scoped custom action handlers |
+| `isMobile` | Explicitly enables mobile component layout; defaults to `false` |
+| `responsive` | Explicitly enables mobile px-to-rem conversion when configured |
 | `fetch` | Supplies a custom request implementation |
 | `showToast` | Connects toast actions to the host UI |
 | `navigate` | Connects URL actions to host navigation |
 | `emit` | Receives events emitted by a card |
 | `copyText` | Connects copy actions to the host clipboard |
 
+The SDK does not infer mobile mode or CSS units from viewport width. Pass only
+`isMobile: true` for mobile layout with px output. To opt into REM conversion,
+also pass `responsive: { mobile: { unit: "rem", rootValue: 100 } }`.
+
 ### Streaming
 
 Use `renderStreamingCard` when the card arrives incrementally from an AI model or server:
@@ -121,6 +126,8 @@ const bot = new BotSDK({
 await bot.renderCard(container, schema);
 ```
 
+`botId` is optional. Omit it when the application uses only one default action scope; provide it when isolating custom handlers or loading per-bot action configuration.
+
 ## Built-in components
 
 The renderer includes:

package/dist/index.d.ts

@@ -29,6 +29,25 @@ interface WebActionContextOptions {
  */
 declare function createWebActionContext(options?: WebActionContextOptions): ActionRunnerContext;
 
+interface ResponsiveMobileOptions {
+    readonly unit: 'rem';
+    readonly rootValue: number;
+}
+interface ResponsiveOptions {
+    readonly mobile?: ResponsiveMobileOptions;
+}
+interface ResponsiveContext {
+    readonly active: boolean;
+    readonly rootValue: number;
+    resolveLength(value: string | number): string;
+    convertCSS(value: string): string;
+}
+/** Reusable REM preset; applied only when passed explicitly as `responsive.mobile`. */
+declare const DEFAULT_MOBILE_RESPONSIVE: ResponsiveMobileOptions;
+/** Convert CSS px lengths while preserving strings, comments, and URLs. */
+declare function convertPixelTokens(value: string, rootValue: number): string;
+declare function createResponsiveContext(isMobile: boolean, responsive?: ResponsiveOptions): ResponsiveContext;
+
 /**
  * renderCard — the primary public API for @antglobal/copilot-cards-web.
  *
@@ -44,8 +63,10 @@ declare function createWebActionContext(options?: WebActionContextOptions): Acti
  */
 
 interface RenderCardOptions extends WebActionContextOptions {
-    /** Force mobile mode; auto-detected from viewport if omitted */
+    /** Enable mobile component layout explicitly (default false). */
     isMobile?: boolean;
+    /** Optional mobile sizing conversion; omitted values preserve px output. */
+    responsive?: ResponsiveOptions;
     /** External variables to merge into schema.variables (overrides schema defaults) */
     variables?: Record<string, any>;
     /** Bot ID — used to look up bot-scoped action handlers */
@@ -262,8 +283,8 @@ declare function connectSSE(instance: StreamingCardInstance, options: SSEConnect
  */
 
 interface BotSDKOptions {
-    /** Bot ID — identifies which bot this instance is for */
-    botId: string;
+    /** Optional bot ID used to scope custom actions and action configuration */
+    botId?: string;
     /** Base URL for business API requests (e.g. 'https://api.example.com') */
     baseUrl?: string;
     /**
@@ -413,7 +434,7 @@ declare function buildStyleString(styles: Record<string, string | number | undef
  * common style helpers. Designed to be used by `renderCard` which
  * passes resolved props via `setData()`.
  *
- * Note: lifecycle management, event binding, and viewport detection
+ * Note: lifecycle management, event binding, and mobile-mode selection
  * are handled externally by `renderCard` / the render pipeline.
  * BaseElement keeps itself lightweight and focused on DOM rendering.
  */
@@ -422,16 +443,18 @@ declare abstract class BaseElement extends HTMLElement {
     protected _node: RenderTreeNode | null;
     protected _props: Record<string, any>;
     protected _isMobile: boolean;
+    protected _responsiveOptions?: ResponsiveOptions;
+    protected _responsive: ResponsiveContext;
     constructor();
     /**
      * Set component data and trigger render.
      * Called by the component renderer (from `renderCard` pipeline).
      */
-    setData(node: RenderTreeNode, props: Record<string, any>, isMobile: boolean): void;
+    setData(node: RenderTreeNode, props: Record<string, any>, isMobile: boolean, responsive?: ResponsiveOptions): void;
     /**
      * Update props only (e.g. on variable change + re-render).
      */
-    updateProps(props: Record<string, any>, isMobile?: boolean): void;
+    updateProps(props: Record<string, any>, isMobile?: boolean, responsive?: ResponsiveOptions): void;
     /**
      * Subclasses must implement this to render their UI into `this.shadowRoot`.
      */
@@ -445,6 +468,8 @@ declare abstract class BaseElement extends HTMLElement {
     protected buildInlineStyle(style?: Record<string, any>, isExpressionResult?: boolean): string;
     /** Resolve a single size value (number → px). */
     protected toCSS(value: string | number): string;
+    /** Assign component markup and convert only its CSS declarations. */
+    protected setShadowHTML(html: string): void;
     /**
      * Escape a value before interpolating it into a double-quoted HTML
      * attribute. Browsers decode the entities before parsing inline CSS, so
@@ -472,7 +497,7 @@ declare class CardText extends BaseElement {
     private _mdPendingUpdate;
     private _tooltipEl;
     private _tooltipTimer;
-    setData(node: RenderTreeNode, props: Record<string, any>, isMobile: boolean): void;
+    setData(node: RenderTreeNode, props: Record<string, any>, isMobile: boolean, responsive?: ResponsiveOptions): void;
     protected render(): void;
     /**
      * Handle incremental content update in streaming mode.
@@ -500,7 +525,7 @@ declare class CardText extends BaseElement {
      * Remove cursor when streaming ends.
      * Called externally when streaming prop changes to false.
      */
-    updateProps(props: Record<string, any>, isMobile?: boolean): void;
+    updateProps(props: Record<string, any>, isMobile?: boolean, responsive?: ResponsiveOptions): void;
     /**
      * Parse markdown to HTML using marked.
      */
@@ -596,6 +621,8 @@ declare class CardButton extends BaseElement {
 declare class CardInput extends BaseElement {
     static readonly is = "ai-card-input";
     protected render(): void;
+    private getAutoFocusControl;
+    private isFirstAvailableAutoFocusInput;
     /** Escape HTML entities for safe insertion. */
     private escapeHtml;
     /** Escape attribute values for safe insertion. */
@@ -789,30 +816,6 @@ declare class CardTag extends BaseElement {
     protected render(): void;
 }
 
-/**
- * CardSelect — Custom Element for a dropdown selector.
- *
- * Schema example:
- * ```json
- * {
- *   "type": "Select",
- *   "props": {
- *     "placeholder": "请选择",
- *     "options": [
- *       { "label": "选项一", "value": "1" },
- *       { "label": "选项二", "value": "2" }
- *     ],
- *     "value": ""
- *   }
- * }
- * ```
- *
- * The value is semi-controlled: a user-picked option shows on the trigger
- * immediately even when no `onChange` action is wired, while any external
- * `props.value` change (e.g. a variable update re-render) overrides the
- * local pick.
- */
-
 declare class CardSelect extends BaseElement {
     private _open;
     private _activeIndex;
@@ -824,7 +827,7 @@ declare class CardSelect extends BaseElement {
     static readonly is = "ai-card-select";
     protected render(): void;
     disconnectedCallback(): void;
-    updateProps(props: Record<string, any>, isMobile?: boolean): void;
+    updateProps(props: Record<string, any>, isMobile?: boolean, responsive?: ResponsiveOptions): void;
     private _setOpen;
     private openWithCurrentOption;
     private handleKeydown;
@@ -1017,6 +1020,8 @@ type InputAffix = string | InputAffixConfig;
 interface InputProps {
     /** Placeholder text */
     placeholder?: string;
+    /** Focus the native input after the component is mounted (default false) */
+    autoFocus?: boolean;
     /** HTML input type: text / textarea / password / number etc. */
     inputType?: 'text' | 'textarea' | 'password' | (string & {});
     /** Label text displayed above the input */
@@ -1191,6 +1196,8 @@ interface SelectStyles {
     option?: Record<string, any>;
     /** Style merged into the selected option */
     selectedOption?: Record<string, any>;
+    /** Arrow wrapper style; overrides arrowSize for declared dimensions */
+    arrow?: Record<string, any>;
 }
 interface SelectProps {
     /** Dropdown options list */
@@ -1217,6 +1224,8 @@ interface SelectProps {
     variant?: SelectVariant;
     /** Accent used for focus and selection states */
     accentColor?: string;
+    /** Dropdown arrow size in px or as a CSS length */
+    arrowSize?: number | string;
     /** Advanced semantic styles for internal parts */
     styles?: SelectStyles;
 }
@@ -1758,7 +1767,7 @@ declare class CardChoiceItem extends BaseElement {
  * for the `renderCard` pipeline to attach events and children.
  */
 
-type ComponentRenderer = (node: RenderTreeNode, props: Record<string, any>, isMobile: boolean) => HTMLElement;
+type ComponentRenderer = (node: RenderTreeNode, props: Record<string, any>, isMobile: boolean, responsive?: ResponsiveOptions) => HTMLElement;
 declare const componentRenderers: Record<string, ComponentRenderer>;
 /**
  * Register a custom component renderer.
@@ -1775,5 +1784,5 @@ 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, LocalActionConfigProvider, RemoteActionConfigProvider, buildStyleString, componentRenderers, connectSSE, connectStreaming, 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, SSEConnectOptions, SelectOption, SelectProps, SelectSize, SelectStyles, SelectVariant, StepIcon, StepItem, StepsProps, StreamingCardInstance, StreamingCardOptions, StreamingConnectOptions, StreamingConnection, SwitchProps, TagProps, TextProps, WebActionContextOptions };
+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 };