@antglobal/copilot-cards-web 0.0.0 → 0.0.20260724033338-dev.13

package/README.md

@@ -1,3 +1,172 @@
-### Marmot NPM
+# @antglobal/copilot-cards-web
 
-placeholder
+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