@antglobal/copilot-cards-web 1.0.0 → 1.0.1

package/README.md

@@ -1 +1,172 @@
-# Marmot NPM
+# @antglobal/copilot-cards-web
+
+Web renderer for schema-driven cards in AI conversations. It turns one JSON schema into interactive Custom Elements for desktop browsers, mobile browsers, and WebViews.
+
+The package includes the core schema and action APIs, responsive rendering, Shadow DOM style isolation, streaming updates, and extensible component registration.
+
+## Installation
+
+```bash
+npm install @antglobal/copilot-cards-web
+```
+
+`@antglobal/copilot-cards-core` is installed automatically.
+
+## Quick start
+
+```ts
+import { renderCard } from "@antglobal/copilot-cards-web";
+
+const container = document.getElementById("card");
+if (!container) throw new Error("Missing #card container");
+
+const schema = {
+  version: "1.0",
+  rootID: "root",
+  elements: {
+    root: {
+      id: "root",
+      type: "Text",
+      props: {
+        content: { type: "static", value: "Hello, Copilot Cards!" },
+      },
+    },
+  },
+  variables: {},
+};
+
+const card = renderCard(container, schema, {
+  emit: (eventName, payload) => {
+    console.log(eventName, payload);
+  },
+  showToast: (message, level) => {
+    console.log(`[${level ?? "info"}] ${message}`);
+  },
+});
+
+card.updateVariables({ userName: "Alice" });
+
+// Dispose when the host view is removed.
+card.dispose();
+```
+
+## Framework usage
+
+The renderer accesses browser APIs and should be loaded on the client in frameworks that perform server-side rendering.
+
+```ts
+const { renderCard } = await import("@antglobal/copilot-cards-web");
+```
+
+In React or Next.js, run the dynamic import inside a client component effect. In Vue, run it after the component is mounted.
+
+## Main API
+
+### `renderCard(container, schema, options?)`
+
+Renders a complete schema and returns a `CardInstance`:
+
+```ts
+interface CardInstance {
+  updateVariables(variables: Record<string, unknown>): void;
+  dispose(): void;
+}
+```
+
+Common render options include:
+
+| Option | Purpose |
+| --- | --- |
+| `variables` | Overrides initial schema variables |
+| `botId` | Selects bot-scoped custom action handlers |
+| `isMobile` | Overrides automatic viewport detection |
+| `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 |
+
+### Streaming
+
+Use `renderStreamingCard` when the card arrives incrementally from an AI model or server:
+
+```ts
+import { renderStreamingCard } from "@antglobal/copilot-cards-web";
+
+const stream = renderStreamingCard(container);
+
+stream.feed(chunk);
+stream.flush();
+stream.dispose();
+```
+
+The package also exports `connectStreaming` and `connectSSE` helpers, plus partial-schema and A2UI adapters.
+
+### `BotSDK`
+
+`BotSDK` groups card instances, bot-scoped action handlers, and declarative action providers behind one host-facing API.
+
+```ts
+import { BotSDK } from "@antglobal/copilot-cards-web";
+
+const bot = new BotSDK({
+  botId: "support-bot",
+  onAction: {
+    trackEvent: async (step) => {
+      console.log(step.params);
+    },
+  },
+});
+
+await bot.renderCard(container, schema);
+```
+
+## Built-in components
+
+The renderer includes:
+
+- Text, Button, Input, Image, Divider
+- Rate, Tag, Select, PasscodeInput
+- Icon, Form, Loading, Progress
+- Steps, Collapse, and sanitized HTML
+
+Components render as isolated `ai-card-*` Custom Elements.
+
+## Custom components
+
+```ts
+import {
+  registerComponent,
+  type ComponentRenderer,
+} from "@antglobal/copilot-cards-web";
+
+const renderStatus: ComponentRenderer = (_node, props) => {
+  const element = document.createElement("div");
+  element.textContent = String(props.label ?? "");
+  return element;
+};
+
+registerComponent("Status", renderStatus);
+```
+
+## Actions
+
+Cards can declaratively request `emit`, `request`, `setVariable`, `toast`, `url`, and `copy` actions. The host remains in control of network access, navigation, notifications, clipboard behavior, and custom business actions.
+
+## Browser requirements
+
+- Custom Elements
+- Shadow DOM
+- `AbortController`
+- Modern JavaScript with ES2020 support
+
+Provide appropriate polyfills when targeting older WebViews.
+
+## Related packages
+
+- `@antglobal/copilot-cards-core` — UI-independent schema, expression, action, lifecycle, and streaming logic.
+- `@antglobal/copilot-cards-mini-program` — native renderer for Alipay and WeChat mini-programs.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ActionRunnerContext, CardSchemaInput, StreamingCommand, CardSchema, StreamingParserOptions, SimpleActionHandler, ActionConfigProvider, ActionChainConfig, RenderTreeNode } from '@antglobal/copilot-cards-core';
-export { A2UIComponent, A2UIEnvelope, ActionChainConfig, ActionConfigProvider, ActionRegistry, ActionRunnerContext, ActionStep, CardSchema, CardSchemaInput, ElementLifecycle, ElementNode, ExpressionContext, ExpressionValue, LegacyCardContentItem, LegacyCardSchema, LegacyTracking, LegacyTrackingType, LifecycleManager, RenderTreeNode, SimpleActionHandler, SlotContent, SlotLayout, a2uiComponentToElement, a2uiToCommand, convertLegacySchema, createLifecycleManager, hasExpression, isA2UIEnvelope, isLegacySchema, normalizeSchema, parseSchema, registerActionHandler, registry, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, validateSchema } from '@antglobal/copilot-cards-core';
+export { A2UIComponent, A2UIEnvelope, ActionChainConfig, ActionConfigProvider, ActionRegistry, ActionRunnerContext, ActionStep, BuiltinIconName, CardSchema, CardSchemaInput, ElementLifecycle, ElementNode, ExpressionContext, ExpressionValue, LegacyCardContentItem, LegacyCardSchema, LegacyTracking, LegacyTrackingType, LifecycleManager, RenderTreeNode, SimpleActionHandler, SlotContent, SlotLayout, a2uiComponentToElement, a2uiToCommand, convertLegacySchema, createLifecycleManager, hasExpression, isA2UIEnvelope, isLegacySchema, normalizeSchema, parseSchema, registerActionHandler, registry, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, validateSchema } from '@antglobal/copilot-cards-core';
 
 /**
  * Core Adapter — bridges @antglobal/copilot-cards-core logic for the web-component layer.
@@ -780,7 +780,7 @@ declare class CardPasscodeInput extends BaseElement {
  * {
  *   "type": "Icon",
  *   "props": {
- *     "name": "check",
+ *     "name": "check_circle",
  *     "src": "https://...",
  *     "size": 24,
  *     "color": "#1677ff"
@@ -1006,13 +1006,13 @@ interface PasscodeInputProps {
     style?: Record<string, any>;
 }
 interface IconProps {
-    /** Built-in icon name (check/close/info/warning/error/success/star/heart/search/arrow_right) or emoji */
+    /** Built-in snake_case icon name or fallback text/emoji */
     name?: string;
-    /** URL to a remote icon image */
+    /** External image URL; takes precedence over name and is not recolored */
     src?: string;
     /** Icon size in px (default 24) */
     size?: number;
-    /** Icon color (default 'currentColor') */
+    /** Built-in SVG color (default currentColor); does not affect src images */
     color?: string;
     /** Inline style object */
     style?: Record<string, any>;

package/dist/{index.esm.js → index.js}

@@ -1,4 +1,4 @@
-import { normalizeSchema, validateSchema, parseSchema, createLifecycleManager, hasExpression, resolveExpression, resolveDeep, resolveExpressionValue, resolveActionRef, runActionSteps, StreamingParser, StreamingEngine, extractPartialSchema, runActionStep, registry } from '@antglobal/copilot-cards-core';
+import { getBuiltinIcon, normalizeSchema, validateSchema, parseSchema, createLifecycleManager, hasExpression, resolveExpression, resolveDeep, resolveExpressionValue, resolveActionRef, runActionSteps, StreamingParser, StreamingEngine, 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';
@@ -2083,10 +2083,11 @@ class CardButton extends BaseElement {
           max-width: 100%;
         }
         .card-btn {
+          position: relative;
+          isolation: isolate;
           display: inline-flex;
           align-items: center;
           justify-content: center;
-          gap: 6px;
           border: none;
           border-radius: 6px;
           cursor: pointer;
@@ -2104,6 +2105,37 @@ class CardButton extends BaseElement {
           width: ${block ? '100%' : 'auto'};
         }
 
+        /* ─── Custom-background-safe interaction overlay ──────── */
+        .card-btn::before {
+          position: absolute;
+          inset: 0;
+          z-index: 0;
+          border-radius: inherit;
+          background: currentColor;
+          opacity: 0;
+          pointer-events: none;
+          content: '';
+          transition: opacity 0.2s ease;
+        }
+        .card-btn:hover:not(:disabled)::before {
+          opacity: 0.08;
+        }
+        .card-btn:active:not(:disabled)::before {
+          opacity: 0.12;
+        }
+        .card-btn-content {
+          position: relative;
+          z-index: 1;
+          display: inline-flex;
+          min-width: 0;
+          max-width: 100%;
+          align-items: center;
+          justify-content: center;
+          gap: 6px;
+          overflow: hidden;
+          text-overflow: ellipsis;
+        }
+
         /* ─── Variants ─────────────────────────── */
         .card-btn.primary {
           background-color: #1677ff;
@@ -2187,7 +2219,7 @@ class CardButton extends BaseElement {
         class="card-btn ${variant} ${isMobile ? 'card-mobile' : 'card-desktop'}"
         ${disabled ? 'disabled' : ''}
         style="${inlineStyle}"
-      >${icon ? `<span class="card-btn-icon">${sanitizeIconHtml(String(icon))}</span>` : ''}${displayText}</button>
+      ><span class="card-btn-content">${icon ? `<span class="card-btn-icon">${sanitizeIconHtml(String(icon))}</span>` : ''}${displayText}</span></button>
     `;
     }
 }
@@ -3396,25 +3428,6 @@ if (typeof customElements !== 'undefined' && !customElements.get(CardPasscodeInp
     customElements.define(CardPasscodeInput.is, CardPasscodeInput);
 }
 
-/**
- * CardIcon — Custom Element for rendering icons.
- *
- * Supports URL-based icons (png/svg) and built-in emoji/SVG icons.
- *
- * Schema example:
- * ```json
- * {
- *   "type": "Icon",
- *   "props": {
- *     "name": "check",
- *     "src": "https://...",
- *     "size": 24,
- *     "color": "#1677ff"
- *   }
- * }
- * ```
- */
-/** Escape a value for safe interpolation into an HTML attribute (double-quoted). */
 function escapeAttr$1(value) {
     return value
         .replace(/&/g, '&amp;')
@@ -3422,43 +3435,56 @@ function escapeAttr$1(value) {
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;');
 }
-/** Escape a value for safe interpolation as HTML element text. */
 function escapeText(value) {
     return value
         .replace(/&/g, '&amp;')
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;');
 }
-/**
- * Reject only genuinely dangerous src schemes (script-bearing / non-image
- * data URIs); everything else — http(s), protocol-relative, absolute and
- * relative paths, blob:, image data URIs — passes through unchanged so no
- * legitimate icon URL is broken. Blocked values fall back to empty.
- */
 function sanitizeImageSrc(src) {
-    const trimmed = String(src).trim();
-    // Strip HTML-entity / whitespace obfuscation, then test the leading scheme.
+    const trimmed = String(src ?? '').trim();
     const scheme = trimmed.replace(/[\s\x00-\x1f]/g, '').toLowerCase();
     if (/^(javascript|vbscript|file):/.test(scheme))
         return '';
-    // Allow data: only for images; block data:text/html and friends.
     if (/^data:/.test(scheme) && !/^data:image\//.test(scheme))
         return '';
     return trimmed;
 }
-// Built-in SVG icon paths (minimal set)
-const BUILTIN_ICONS = {
-    check: '<path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z"/>',
-    close: '<path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/>',
-    info: '<path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-6h2v6zm0-8h-2V7h2v2z"/>',
-    warning: '<path d="M1 21h22L12 2 1 21zm12-3h-2v-2h2v2zm0-4h-2v-4h2v4z"/>',
-    error: '<path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"/>',
-    success: '<path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z"/>',
-    star: '<path d="M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z"/>',
-    heart: '<path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/>',
-    search: '<path d="M15.5 14h-.79l-.28-.27C15.41 12.59 16 11.11 16 9.5 16 5.91 13.09 3 9.5 3S3 5.91 3 9.5 5.91 16 9.5 16c1.61 0 3.09-.59 4.23-1.57l.27.28v.79l5 4.99L20.49 19l-4.99-5zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"/>',
-    arrow_right: '<path d="M10 6L8.59 7.41 13.17 12l-4.58 4.59L10 18l6-6z"/>',
-};
+function renderIconContent(input) {
+    const size = Number(input.size) || 24;
+    const name = input.name == null ? undefined : String(input.name);
+    if (input.src) {
+        return `<img class="icon-img" src="${escapeAttr$1(sanitizeImageSrc(input.src))}" ` +
+            `width="${size}" height="${size}" alt="${escapeAttr$1(name ?? 'icon')}" />`;
+    }
+    const icon = getBuiltinIcon(name);
+    if (icon) {
+        return `<svg class="icon-svg" viewBox="${escapeAttr$1(icon.viewBox)}" width="${size}" ` +
+            `height="${size}" color="${escapeAttr$1(String(input.color ?? 'currentColor'))}" ` +
+            `aria-hidden="true">${icon.body}</svg>`;
+    }
+    return `<span class="icon-text" style="font-size:${size}px; line-height:1;">` +
+        `${escapeText(name ?? '?')}</span>`;
+}
+
+/**
+ * CardIcon — Custom Element for rendering icons.
+ *
+ * Supports URL-based icons (png/svg) and built-in emoji/SVG icons.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Icon",
+ *   "props": {
+ *     "name": "check_circle",
+ *     "src": "https://...",
+ *     "size": 24,
+ *     "color": "#1677ff"
+ *   }
+ * }
+ * ```
+ */
 class CardIcon extends BaseElement {
     render() {
         if (!this.shadowRoot || !this._node)
@@ -3466,26 +3492,12 @@ class CardIcon extends BaseElement {
         const { name, src, size = 24, color = 'currentColor', style, isExpressionResultStyle, } = this._props;
         const inlineStyle = this.buildInlineStyle(style, isExpressionResultStyle);
         const iconSize = Number(size) || 24;
-        let iconContent;
-        if (src) {
-            // URL-based icon (image). Both src and alt are interpolated into HTML
-            // attributes, so they must be escaped — an unescaped `"` in src would
-            // break out of the attribute and inject markup (e.g. onerror handlers).
-            // src is additionally protocol-gated to http(s)/data-image only.
-            const safeSrc = escapeAttr$1(sanitizeImageSrc(src));
-            const safeAlt = escapeAttr$1(String(name ?? 'icon'));
-            iconContent = `<img class="icon-img" src="${safeSrc}" width="${iconSize}" height="${iconSize}" alt="${safeAlt}" />`;
-        }
-        else if (name && BUILTIN_ICONS[name]) {
-            // Built-in SVG — `name` is validated against the allow-list, so the SVG
-            // body is a trusted constant; `color` is escaped defensively.
-            iconContent = `<svg class="icon-svg" viewBox="0 0 24 24" width="${iconSize}" height="${iconSize}" fill="${escapeAttr$1(String(color))}">${BUILTIN_ICONS[name]}</svg>`;
-        }
-        else {
-            // Fallback: show name as text (emoji support). Escape as element text so
-            // an arbitrary `name` can't inject markup.
-            iconContent = `<span class="icon-text" style="font-size:${iconSize}px; line-height:1;">${escapeText(String(name ?? '?'))}</span>`;
-        }
+        const iconContent = renderIconContent({
+            name,
+            src,
+            size: iconSize,
+            color,
+        });
         this.shadowRoot.innerHTML = `
       <style>
         :host {
@@ -7078,4 +7090,3 @@ class RemoteActionConfigProvider {
 }
 
 export { BaseElement, BotSDK, CardButton, CardCollapse, CardDivider, CardForm, CardHtml, CardIcon, CardImage, CardInput, CardLoading, CardPasscodeInput, CardProgress, CardRate, CardSelect, CardSteps, CardTag, CardText, LocalActionConfigProvider, RemoteActionConfigProvider, buildStyleString, componentRenderers, connectSSE, connectStreaming, createWebActionContext, isMobileViewport, onViewportChange, pxToRem, pxToVw, registerComponent, renderCard, renderStreamingCard, resolveSize, sanitizeHtml, trimIncompleteTag };
-//# sourceMappingURL=index.esm.js.map

package/package.json

@@ -1,22 +1,23 @@
 {
   "name": "@antglobal/copilot-cards-web",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Web Component renderer for copilot bot card SDK — PC + Mobile + WebView unified rendering via Custom Elements",
-  "main": "dist/index.cjs.js",
-  "module": "dist/index.esm.js",
-  "types": "dist/index.d.ts",
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.esm.js",
-      "require": "./dist/index.cjs.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "rollup -c"
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p ../copilot-cards-web/tsconfig.json --noEmit && rollup -c"
   },
   "keywords": [
     "copilot",
@@ -27,14 +28,13 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@antglobal/copilot-cards-core": "^1.0.0",
+    "@antglobal/copilot-cards-core": "^1.0.1",
     "echarts": "^5.6.0",
     "marked": "^18.0.5",
     "tslib": "^2.8.1",
     "vanilla-calendar-pro": "^3.1.0"
   },
   "devDependencies": {
-    "@rollup/plugin-typescript": "^11.1.0",
     "@types/node": "^20",
     "rollup": "^4.9.0",
     "rollup-plugin-dts": "^6.1.0",