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

@@ -42,6 +42,7 @@ interface ResponsiveContext {
     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;
@@ -62,9 +63,9 @@ declare function createResponsiveContext(isMobile: boolean, responsive?: Respons
  */
 
 interface RenderCardOptions extends WebActionContextOptions {
-    /** Force mobile mode; auto-detected from viewport if omitted */
+    /** Enable mobile component layout explicitly (default false). */
     isMobile?: boolean;
-    /** Mobile sizing conversion. `isMobile: true` defaults to rem/rootValue 100. */
+    /** 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>;
@@ -282,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;
     /**
@@ -433,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.
  */
@@ -620,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. */
@@ -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 */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { getBuiltinIcon, cloneJsonData, createLifecycleManager, materializeCard, resolveActionRef, createA2UIParameterResolver, createExpressionContext, resolveA2UIDeep, hasExpression, resolveExpression, resolveDeep, resolveExpressionValue, replaceRootContents, isBoundRenderTreeNode, runActionSteps, normalizeSchema, validateSchema, requiresBindingMaterialization, parseSchema, StreamingParser, StreamingEngine, findAffectedRepeatOwners, bindingTopologyFingerprint, findTemplateRepeatOwners, extractPartialSchema, runActionStep, registry } from '@antglobal/copilot-cards-core';
+import { getBuiltinIcon, cloneJsonData, createLifecycleManager, materializeCard, createA2UIParameterResolver, createExpressionContext, resolveActionRef, replaceRootContents, resolveA2UIDeep, hasExpression, resolveExpression, resolveDeep, resolveExpressionValue, isBoundRenderTreeNode, runActionSteps, normalizeSchema, validateSchema, requiresBindingMaterialization, parseSchema, StreamingParser, StreamingEngine, findAffectedRepeatOwners, bindingTopologyFingerprint, findTemplateRepeatOwners, extractPartialSchema, runActionStep, registry } from '@antglobal/copilot-cards-core';
 export { ActionRegistry, a2uiComponentToElement, a2uiToCommand, convertLegacySchema, createLifecycleManager, hasExpression, isA2UIEnvelope, isLegacySchema, normalizeSchema, parseSchema, registerActionHandler, registry, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, validateSchema } from '@antglobal/copilot-cards-core';
 import * as echarts from 'echarts/core';
 import { LineChart, BarChart, PieChart, ScatterChart, FunnelChart, HeatmapChart } from 'echarts/charts';
@@ -96,6 +96,7 @@ function buildStyleString(styles) {
         .join(';');
 }
 
+/** Reusable REM preset; applied only when passed explicitly as `responsive.mobile`. */
 const DEFAULT_MOBILE_RESPONSIVE = Object.freeze({
     unit: 'rem',
     rootValue: 100,
@@ -236,10 +237,10 @@ function convertPixelTokens(value, rootValue) {
     return result;
 }
 function createResponsiveContext(isMobile, responsive) {
-    const mobile = responsive?.mobile ?? DEFAULT_MOBILE_RESPONSIVE;
-    const unit = mobile.unit;
-    const rootValue = mobile.rootValue;
-    if (!Number.isFinite(rootValue) || rootValue <= 0) {
+    const mobile = responsive?.mobile;
+    const unit = mobile?.unit;
+    const rootValue = mobile?.rootValue ?? DEFAULT_MOBILE_RESPONSIVE.rootValue;
+    if (mobile && (!Number.isFinite(rootValue) || rootValue <= 0)) {
         throw new Error('[renderCard] responsive.mobile.rootValue must be a positive number');
     }
     const active = isMobile && unit === 'rem';
@@ -1647,7 +1648,7 @@ function renderTableSlot(container, slotContent) {
  * 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.
  */
@@ -2681,7 +2682,7 @@ class CardInput extends BaseElement {
     render() {
         if (!this.shadowRoot || !this._node)
             return;
-        const { placeholder = '', inputType = 'text', label, defaultValue = '', disabled = false, readonly: readOnly = false, maxLength, rows, min, max, step = 1, controls = true, prefix, suffix, style, inputStyle, isExpressionResultStyle, } = this._props;
+        const { placeholder = '', autoFocus = false, inputType = 'text', label, defaultValue = '', disabled = false, readonly: readOnly = false, maxLength, rows, min, max, step = 1, controls = true, prefix, suffix, style, inputStyle, isExpressionResultStyle, } = this._props;
         const inlineStyle = this.buildInlineStyle(style, isExpressionResultStyle);
         const legacyInputStyle = style && typeof style === 'object' && style.resize != null
             ? { resize: style.resize }
@@ -2967,6 +2968,14 @@ class CardInput extends BaseElement {
                     detail: { value: inputEl.value },
                 }));
             });
+            if (autoFocus && !disabled) {
+                queueMicrotask(() => {
+                    const control = this.getAutoFocusControl();
+                    if (control && this.isFirstAvailableAutoFocusInput()) {
+                        control.focus();
+                    }
+                });
+            }
             if (isNumber &&
                 showNumberStepper &&
                 inputEl instanceof HTMLInputElement) {
@@ -2995,6 +3004,22 @@ class CardInput extends BaseElement {
         }
     }
     // ─── Helpers ──────────────────────────────────────────────────
+    getAutoFocusControl() {
+        if (!this.isConnected
+            || !this._props.autoFocus
+            || this.hasAttribute('data-disabled')) {
+            return null;
+        }
+        const control = this.shadowRoot?.querySelector('.card-input');
+        return control && !control.disabled ? control : null;
+    }
+    isFirstAvailableAutoFocusInput() {
+        const root = this.getRootNode();
+        if (!('querySelectorAll' in root))
+            return false;
+        const firstAvailable = Array.from(root.querySelectorAll(CardInput.is)).find(input => input.getAutoFocusControl() !== null);
+        return firstAvailable === this;
+    }
     /** Escape HTML entities for safe insertion. */
     escapeHtml(str) {
         return str
@@ -4716,7 +4741,7 @@ class CardForm extends BaseElement {
         this._bindEvents(fields, disabled);
     }
     _renderField(field, index) {
-        const { name, label, type = 'text', placeholder = '', required = false, rules = [], prefix, suffix, options = [], length = 6, } = field;
+        const { name, label, type = 'text', placeholder = '', required = false, rules = [], prefix, suffix, length = 6, } = field;
         const val = this._values[name] ?? '';
         const error = this._errors[name] || '';
         const errorClass = error ? 'error' : '';
@@ -7713,18 +7738,9 @@ function renderBoundCard(container, schema, options) {
     let currentMaterialized;
     let revision = 0;
     let disposed = false;
-    let isMobile = options.isMobile ?? isMobileViewport();
+    const isMobile = options.isMobile === true;
     let actionQueue = Promise.resolve();
     let lifecycleQueue = Promise.resolve();
-    const removeViewportListener = options.isMobile == null
-        ? onViewportChange((mobile) => {
-            if (disposed)
-                return;
-            isMobile = mobile;
-            const candidate = prepareCandidate(variables);
-            publishDOM(candidate, false);
-        })
-        : () => { };
     function expressionContextFor(node) {
         return isBoundRenderTreeNode(node)
             ? createExpressionContext(node.scope)
@@ -8041,7 +8057,6 @@ function renderBoundCard(container, schema, options) {
                 return;
             disposed = true;
             abortController.abort();
-            removeViewportListener();
             disposeChartsIn(container);
             container.replaceChildren();
             const lifecycleNodes = [...activeLifecycleNodes.entries()];
@@ -8192,13 +8207,7 @@ function renderStaticCard(container, schema, options) {
     }
     let actionContext = buildActionContext();
     // 5. Responsive
-    let isMobile = options.isMobile ?? isMobileViewport();
-    const removeViewportListener = options.isMobile == null
-        ? onViewportChange((mobile) => {
-            isMobile = mobile;
-            rerender();
-        })
-        : () => { };
+    const isMobile = options.isMobile === true;
     // 6. Schema-level action definitions (for string references in events)
     const schemaActions = schema.actions ?? {};
     // 7. Render function
@@ -8222,7 +8231,6 @@ function renderStaticCard(container, schema, options) {
     return {
         dispose() {
             abortController.abort();
-            removeViewportListener();
             lifecycleManager.dispose(actionContext);
             disposeChartsIn(container);
             container.innerHTML = '';
@@ -8495,7 +8503,7 @@ function renderStreamingCard(container, options = {}) {
     let partialVariablesSent = false;
     let partialFinalized = false;
     let variables = { ...options.variables };
-    let isMobile = options.isMobile ?? isMobileViewport();
+    const isMobile = options.isMobile === true;
     let currentSchema = null;
     let currentSurfaceId = null;
     let currentMaterialized = null;
@@ -8507,16 +8515,6 @@ function renderStreamingCard(container, options = {}) {
     const activeBoundLifecycles = new Map();
     const mountedBoundLifecycles = new Map();
     const boundLifecycleGenerations = new Map();
-    // Responsive viewport detection
-    const removeViewportListener = options.isMobile == null
-        ? onViewportChange((mobile) => {
-            isMobile = mobile;
-            // Re-render all elements with new mobile state if schema exists
-            if (currentSchema) {
-                rerenderAll();
-            }
-        })
-        : () => { };
     // ─── Action Context ─────────────────────────────────────────────
     function buildActionContext() {
         return {
@@ -9888,14 +9886,6 @@ function renderStreamingCard(container, options = {}) {
             console.warn('[renderStreamingCard] Deferred render (incomplete schema):', error);
         }
     }
-    /**
-     * Re-render all elements (viewport changes — isMobile affects every renderer's
-     * output, so the incremental diff cache cannot be reused here).
-     */
-    function rerenderAll() {
-        actionContext = buildActionContext();
-        safeRenderFull();
-    }
     // ─── Engine Event Handlers ──────────────────────────────────────
     const engine = new StreamingEngine({
         onSurfaceCreated(surfaceId, schemaInput) {
@@ -10240,7 +10230,7 @@ function renderStreamingCard(container, options = {}) {
                 }
             }
         },
-        onSurfaceDeleted(surfaceId) {
+        onSurfaceDeleted(_surfaceId) {
             disposeChartsIn(container); // release old ECharts instances before clearing
             container.innerHTML = '';
             elementMap.clear();
@@ -10335,7 +10325,6 @@ function renderStreamingCard(container, options = {}) {
             disposed = true;
             boundRevision += 1;
             abortController.abort();
-            removeViewportListener();
             teardownBoundLifecycles();
             lifecycleManager.dispose(actionContext);
             disposeChartsIn(container); // release ECharts instances before clearing
@@ -10504,7 +10493,7 @@ class BotSDK {
         this._instances = [];
         /** Declarative action chains loaded from actionProvider */
         this._actionChains = new Map();
-        this.botId = options.botId;
+        this.botId = options.botId ?? '';
         this.baseUrl = options.baseUrl ?? '';
         // Source B: Batch-register action handler functions (sync, immediate)
         if (options.onAction) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antglobal/copilot-cards-web",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "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.4",
+    "@antglobal/copilot-cards-core": "^1.0.5",
     "echarts": "^5.6.0",
     "marked": "^18.0.5",
     "tslib": "^2.8.1",