@antglobal/copilot-cards-web 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -445,6 +445,12 @@ 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;
+    /**
+     * Escape a value before interpolating it into a double-quoted HTML
+     * attribute. Browsers decode the entities before parsing inline CSS, so
+     * valid CSS strings keep working while quotes cannot create attributes.
+     */
+    private escapeAttribute;
     /**
      * CSS properties whose numeric values are unitless — appending `px`
      * to these produces invalid CSS the browser silently drops
@@ -573,12 +579,11 @@ declare class CardButton extends BaseElement {
  * {
  *   "type": "Input",
  *   "props": {
- *     "placeholder": "Enter your name",
- *     "inputType": "text",
- *     "variableKey": "userName",
- *     "label": "Name",
- *     "maxLength": 100,
- *     "disabled": false,
+ *     "placeholder": "Phone Number",
+ *     "inputType": "tel",
+ *     "variableKey": "phone",
+ *     "prefix": "+86",
+ *     "suffix": { "name": "info", "size": 18 },
  *     "style": { "width": 300 }
  *   },
  *   "events": {
@@ -595,6 +600,7 @@ declare class CardInput extends BaseElement {
     private escapeHtml;
     /** Escape attribute values for safe insertion. */
     private escapeAttr;
+    private _domId;
 }
 
 /**
@@ -685,6 +691,81 @@ declare class CardRate extends BaseElement {
     protected render(): void;
     /** Reset internal state when props update externally */
     updateProps(props: Record<string, any>, isMobile?: boolean): void;
+    private commit;
+    private normalizeValue;
+    private escapeAttr;
+}
+
+/**
+ * CardCounter — Custom Element for a numeric stepper (−/value/+).
+ *
+ * A self-contained value control: two buttons decrement / increment the
+ * middle number within [min, max] by `step`, disabling each button at its
+ * bound. Both the icons and every part's style are configurable.
+ *
+ * The value is synced to schema variables the same way `Input` does — an
+ * `input` event drives `variableKey` auto-sync (no re-render), while a
+ * `change` event lets `onChange` actions read `${_event.value}`.
+ *
+ * Controlled vs uncontrolled:
+ *   • Uncontrolled — set a static `defaultValue` and (optionally) a
+ *     `variableKey`. Clicks update the internal value silently; the value is
+ *     available to later actions (e.g. form submit) but nothing else re-renders.
+ *   • Controlled — bind `value` to a variable (`"value": "${qty}"`) and wire an
+ *     `onChange` → `setVariable`. Because `setVariable` rebuilds the DOM, the
+ *     stepper must read its value from that variable or it will visually reset
+ *     to `defaultValue` on every change. Prefer this when other nodes display
+ *     the same value.
+ *
+ * Schema example:
+ * ```json
+ * {
+ *   "type": "Counter",
+ *   "props": {
+ *     "defaultValue": 1,
+ *     "min": 1,
+ *     "max": 99,
+ *     "step": 1,
+ *     "variableKey": "qty",
+ *     "size": 28,
+ *     "plusIcon": { "name": "+" },
+ *     "minusIcon": { "name": "−" },
+ *     "plusStyle": { "background": "#2f3542", "color": "#fff" }
+ *   },
+ *   "events": {
+ *     "onChange": [{ "type": "setVariable", "params": { "key": "qty", "value": "${_event.value}" } }]
+ *   }
+ * }
+ * ```
+ */
+
+declare class CardCounter extends BaseElement {
+    static readonly is = "ai-card-counter";
+    /** Internal interactive value (tracks clicks before external update) */
+    private _currentValue;
+    protected render(): void;
+    /** Clamp, de-dup, update internal value and emit input + change. */
+    private commit;
+    private clamp;
+    /** Trim binary-float drift from decimal steps (e.g. 0.1 + 0.2). */
+    private round;
+    /**
+     * Default minus glyph — a rounded stroke line, drawn in a symmetric
+     * 24×24 viewBox centered at (12,12). The SVG fills the button, so the
+     * mark is guaranteed centered on both axes (unlike the source's
+     * asymmetric 7×2 box, whose line sat above its own midline).
+     */
+    private defaultMinusGlyph;
+    /** Default plus glyph — a rounded stroke cross centered at (12,12). */
+    private defaultPlusGlyph;
+    /**
+     * Build the glyph inside a button.
+     * Priority: icon.src (image) > icon.name (emoji / text) > fallback (default SVG).
+     */
+    private renderIcon;
+    /** Reset internal state when props update externally. */
+    updateProps(props: Record<string, any>, isMobile?: boolean): void;
+    private escapeAttr;
 }
 
 /**
@@ -734,6 +815,7 @@ declare class CardTag extends BaseElement {
 
 declare class CardSelect extends BaseElement {
     private _open;
+    private _activeIndex;
     /** Option picked locally; shown until props.value changes externally. */
     private _localValue;
     /** Last seen props.value — detects external changes vs. re-renders. */
@@ -742,7 +824,15 @@ declare class CardSelect extends BaseElement {
     static readonly is = "ai-card-select";
     protected render(): void;
     disconnectedCallback(): void;
+    updateProps(props: Record<string, any>, isMobile?: boolean): void;
     private _setOpen;
+    private openWithCurrentOption;
+    private handleKeydown;
+    private findNextEnabled;
+    private commit;
+    private escapeAttr;
+    private escapeText;
+    private applyHostStyles;
 }
 
 /**
@@ -827,8 +917,20 @@ declare class CardForm extends BaseElement {
     private _submitted;
     protected render(): void;
     private _renderField;
+    private _initializeSelectFields;
+    private _selectProps;
+    private _initializeRateFields;
+    private _rateProps;
+    private _renderAffix;
     private _bindEvents;
+    private _syncPasscodeValue;
     private _validate;
+    private _validateField;
+    private _ruleMessage;
+    private _updateFieldValidation;
+    private _escapeHtml;
+    private _escapeAttr;
+    private _domId;
     updateProps(props: Record<string, any>, isMobile?: boolean): void;
 }
 
@@ -895,6 +997,23 @@ interface ButtonProps {
     /** Inline style object */
     style?: Record<string, any>;
 }
+interface InputAffixConfig {
+    /** Static text. When present, it takes precedence over icon fields. */
+    text?: string;
+    /** Built-in icon name or fallback text/emoji */
+    name?: string;
+    /** External image URL; takes precedence over name */
+    src?: string;
+    /** Icon or image size in px */
+    size?: number;
+    /** Built-in icon color */
+    color?: string;
+    /** Accessible description for icon or image affixes */
+    ariaLabel?: string;
+    /** Inline style applied to the affix wrapper */
+    style?: Record<string, any>;
+}
+type InputAffix = string | InputAffixConfig;
 interface InputProps {
     /** Placeholder text */
     placeholder?: string;
@@ -904,16 +1023,32 @@ interface InputProps {
     label?: string;
     /** Initial value */
     defaultValue?: string;
+    /** Reactive variable the value is synced into */
+    variableKey?: string;
+    /** Static content rendered before the editable value */
+    prefix?: InputAffix;
+    /** Static content rendered after the editable value */
+    suffix?: InputAffix;
     /** Whether the input is disabled */
     disabled?: boolean;
     /** Whether the input is read-only */
     readonly?: boolean;
     /** Maximum character length */
     maxLength?: number;
+    /** Minimum value for number inputs */
+    min?: number;
+    /** Maximum value for number inputs */
+    max?: number;
+    /** Increment used by number inputs (default 1) */
+    step?: number;
+    /** Whether number inputs show built-in step controls (default true) */
+    controls?: boolean;
     /** Number of rows for textarea (default 3) */
     rows?: number;
-    /** Inline style object */
+    /** Inline style applied to the combined input control */
     style?: Record<string, any>;
+    /** Inline style applied directly to the native input or textarea */
+    inputStyle?: Record<string, any>;
 }
 interface ImageProps {
     /** Image URL */
@@ -948,20 +1083,84 @@ interface DividerProps {
 interface RateProps {
     /** Current rating value (default 0) */
     value?: number;
+    /** Initial value for uncontrolled usage */
+    defaultValue?: number;
     /** Total number of stars (default 5) */
     count?: number;
+    /** Whether the rating is disabled */
+    disabled?: boolean;
     /** Whether the rating is read-only (default false) */
     readonly?: boolean;
     /** Whether half-star selection is allowed (default false) */
     allowHalf?: boolean;
+    /** Whether clicking the current value clears it (default true) */
+    allowClear?: boolean;
     /** Star size in px (default 24) */
     size?: number;
+    /** Gap between stars in px (default 4) */
+    gap?: number;
     /** Active star color (default '#fadb14') */
     color?: string;
     /** Inactive star color (default '#e8e8e8') */
     inactiveColor?: string;
+    /** Reactive variable the value is synced into */
+    variableKey?: string;
+    /** Accessible label for the slider */
+    ariaLabel?: string;
     /** Inline style object */
     style?: Record<string, any>;
+    /** Style applied to every star */
+    starStyle?: Record<string, any>;
+    /** Style applied to active stars */
+    activeStarStyle?: Record<string, any>;
+    /** Style applied to inactive stars */
+    inactiveStarStyle?: Record<string, any>;
+}
+interface CounterIcon {
+    /** URL to an icon image (png/svg); http(s) or image data URI */
+    src?: string;
+    /** Built-in icon name or emoji / text glyph */
+    name?: string;
+}
+interface CounterProps {
+    /** Initial value (default `min`, falling back to 0) */
+    defaultValue?: number;
+    /** Current external value; takes precedence over defaultValue */
+    value?: number;
+    /** Minimum value (default 0) */
+    min?: number;
+    /** Maximum value (default Infinity) */
+    max?: number;
+    /** Increment/decrement step (default 1) */
+    step?: number;
+    /** Disable the whole control (default false) */
+    disabled?: boolean;
+    /** Read-only: show the value, disable both buttons (default false) */
+    readonly?: boolean;
+    /** Button diameter in px (default 28) */
+    size?: number;
+    /** Min width of the value text in px (default 32) */
+    valueWidth?: number;
+    /** Reactive variable the value is synced into */
+    variableKey?: string;
+    /** Accessible label for the decrement button */
+    decreaseAriaLabel?: string;
+    /** Accessible label for the increment button */
+    increaseAriaLabel?: string;
+    /** Custom minus-button icon ({ src | name }); defaults to '−' */
+    minusIcon?: CounterIcon;
+    /** Custom plus-button icon ({ src | name }); defaults to '+' */
+    plusIcon?: CounterIcon;
+    /** Inline style for the outer wrapper */
+    style?: Record<string, any>;
+    /** Inline style applied to both buttons */
+    buttonStyle?: Record<string, any>;
+    /** Inline style for the minus button (merged over `buttonStyle`) */
+    minusStyle?: Record<string, any>;
+    /** Inline style for the plus button (merged over `buttonStyle`) */
+    plusStyle?: Record<string, any>;
+    /** Inline style for the value text */
+    valueStyle?: Record<string, any>;
 }
 interface TagProps {
     /** Tag label text */
@@ -978,18 +1177,145 @@ interface TagProps {
 interface SelectOption {
     label: string;
     value: string;
+    /** Whether this option cannot be selected */
+    disabled?: boolean;
+}
+type SelectSize = 'small' | 'medium' | 'large';
+type SelectVariant = 'outlined' | 'filled' | 'borderless';
+interface SelectStyles {
+    /** Select trigger style */
+    trigger?: Record<string, any>;
+    /** Dropdown panel style */
+    dropdown?: Record<string, any>;
+    /** Style applied to every option */
+    option?: Record<string, any>;
+    /** Style merged into the selected option */
+    selectedOption?: Record<string, any>;
 }
 interface SelectProps {
     /** Dropdown options list */
     options?: SelectOption[];
     /** Placeholder text (default '请选择') */
     placeholder?: string;
+    /** Initial value for uncontrolled usage */
+    defaultValue?: string;
     /** Currently selected value */
     value?: string;
+    /** Reactive variable the value is synced into */
+    variableKey?: string;
     /** Whether the select is disabled (default false) */
     disabled?: boolean;
-    /** Inline style object */
+    /** Whether the selection is read-only */
+    readonly?: boolean;
+    /** Accessible label for the combobox */
+    ariaLabel?: string;
+    /** Component layout style, such as width and margin */
+    style?: Record<string, any>;
+    /** Component size preset (default medium) */
+    size?: SelectSize;
+    /** Trigger appearance preset (default outlined) */
+    variant?: SelectVariant;
+    /** Accent used for focus and selection states */
+    accentColor?: string;
+    /** Advanced semantic styles for internal parts */
+    styles?: SelectStyles;
+}
+interface SwitchProps {
+    /** Current external checked state */
+    checked?: boolean;
+    /** Initial checked state for uncontrolled usage */
+    defaultChecked?: boolean;
+    /** Whether the switch is disabled */
+    disabled?: boolean;
+    /** Whether the switch is read-only but remains focusable */
+    readonly?: boolean;
+    /** Track height in px (default 22; default width is 44) */
+    size?: number;
+    /** Track color while checked */
+    activeColor?: string;
+    /** Track color while unchecked */
+    inactiveColor?: string;
+    /** Thumb color */
+    thumbColor?: string;
+    /** Reactive variable the boolean value is synced into */
+    variableKey?: string;
+    /** Accessible label */
+    ariaLabel?: string;
+    /** Outer wrapper style */
+    style?: Record<string, any>;
+    /** Track style */
+    trackStyle?: Record<string, any>;
+    /** Thumb style */
+    thumbStyle?: Record<string, any>;
+}
+type ChoiceListValue = string | string[] | null;
+interface ChoiceListProps {
+    /** Single-select or multi-select behavior (default single) */
+    selectionMode?: 'single' | 'multiple';
+    /** Current external selection */
+    value?: ChoiceListValue;
+    /** Initial uncontrolled selection */
+    defaultValue?: ChoiceListValue;
+    /** Whether a selected single choice can be cleared */
+    allowClear?: boolean;
+    /** Maximum number of selected items in multiple mode */
+    maxSelected?: number;
+    /** Disable selection and all slotted interactions */
+    disabled?: boolean;
+    /** Lock selection while keeping slotted interactions available */
+    readonly?: boolean;
+    /** List flow direction */
+    direction?: 'vertical' | 'horizontal';
+    /** Gap between direct ChoiceItem children */
+    gap?: number | string;
+    /** Item shell preset; content composition is independent (default plain) */
+    variant?: 'plain' | 'outlined';
+    /** Position of every selection indicator */
+    indicatorPosition?: 'start' | 'end';
+    /** Reactive variable the selection is synced into */
+    variableKey?: string;
+    /** Accessible group label */
+    ariaLabel?: string;
+    /** List wrapper style */
+    style?: Record<string, any>;
+    /** Default style merged into every ChoiceItem */
+    itemStyle?: Record<string, any>;
+    /** Style merged into selected ChoiceItems */
+    selectedItemStyle?: Record<string, any>;
+    /** Default style for every selection indicator */
+    indicatorStyle?: Record<string, any>;
+    /** Style merged into selected indicators */
+    selectedIndicatorStyle?: Record<string, any>;
+    /** Checked mark used by multiple mode; defaults to built-in `check_bold` */
+    checkedIcon?: ChoiceIndicatorIcon;
+}
+interface ChoiceIndicatorIcon {
+    /** Built-in icon name or fallback text/emoji */
+    name?: string;
+    /** External image URL; takes precedence over name */
+    src?: string;
+    /** Icon size in px */
+    size?: number;
+    /** Built-in SVG color */
+    color?: string;
+}
+interface ChoiceItemProps {
+    /** Unique selection value within the direct parent ChoiceList */
+    value: string;
+    /** Disable this item and all slotted interactions */
+    disabled?: boolean;
+    /** Accessible item label; falls back to value */
+    ariaLabel?: string;
+    /** Item shell style */
     style?: Record<string, any>;
+    /** Style merged while selected */
+    selectedStyle?: Record<string, any>;
+    /** Per-item indicator style */
+    indicatorStyle?: Record<string, any>;
+    /** Per-item selected indicator style */
+    selectedIndicatorStyle?: Record<string, any>;
+    /** Per-item checked mark override */
+    checkedIcon?: ChoiceIndicatorIcon;
 }
 interface PasscodeInputProps {
     /** Number of passcode cells (default 6, max 10) */
@@ -1028,16 +1354,45 @@ interface FormField {
     placeholder?: string;
     /** Whether the field is required */
     required?: boolean;
+    /** Declarative validation rules, evaluated in array order */
+    rules?: FormRule[];
+    /** Static content rendered before text-like fields */
+    prefix?: InputAffix;
+    /** Static content rendered after text-like fields */
+    suffix?: InputAffix;
     /** Options for select type */
     options?: {
         label: string;
         value: string;
+        disabled?: boolean;
     }[];
+    /** Style forwarded to Select trigger or Rate wrapper; currently ignored by other field types */
+    style?: Record<string, any>;
+    /** Select size preset */
+    size?: SelectSize;
+    /** Select trigger appearance preset */
+    variant?: SelectVariant;
+    /** Select focus and selection accent */
+    accentColor?: string;
+    /** Advanced semantic styles for select fields */
+    styles?: SelectStyles;
     /** Number of cells for passcode type (default 6) */
     length?: number;
     /** Initial value */
     defaultValue?: any;
 }
+interface FormRule {
+    /** Whether an empty value is invalid */
+    required?: boolean;
+    /** Regular expression source used to validate the string value */
+    pattern?: string;
+    /** Minimum string length */
+    minLength?: number;
+    /** Maximum string length */
+    maxLength?: number;
+    /** Error message shown when this rule fails */
+    message?: string;
+}
 interface FormProps {
     /** Form field definitions */
     fields?: FormField[];
@@ -1045,9 +1400,13 @@ interface FormProps {
     submitText?: string;
     /** Form layout direction (default 'vertical') */
     layout?: 'vertical' | 'horizontal';
-    /** Whether the entire form is disabled (default false) */
+    /** Disables submission and Select/Rate interaction; native fields stop syncing but remain editable */
     disabled?: boolean;
-    /** Inline style object */
+    /** Style merged into invalid field controls */
+    invalidStyle?: Record<string, any>;
+    /** Style applied to validation messages */
+    errorStyle?: Record<string, any>;
+    /** Inline style applied to the inner form wrapper */
     style?: Record<string, any>;
 }
 interface LoadingProps {
@@ -1143,6 +1502,8 @@ interface StepsProps {
     items?: StepItem[];
     /** Global icon size in px (default 28) */
     iconSize?: number;
+    /** Title and description layout within each step (default vertical) */
+    textLayout?: 'vertical' | 'horizontal';
     /** Title text style overrides */
     titleProps?: {
         fontSize?: string;
@@ -1219,6 +1580,7 @@ declare class CardProgress extends BaseElement {
  *       { "title": "Final review", "status": "pending" }
  *     ],
  *     "iconSize": 28,
+ *     "textLayout": "vertical",
  *     "titleProps": { "fontSize": "14px", "fontWeight": 500, "color": "#1a1a1a" },
  *     "descriptionProps": { "fontSize": "12px", "color": "#8c8c8c" },
  *     "connector": { "width": 2, "minHeight": 24, "style": "solid", "color": "#e8e8e8", "completedColor": "#52c41a" }
@@ -1324,6 +1686,70 @@ declare class CardHtml extends BaseElement {
     protected render(): void;
 }
 
+declare class CardSwitch extends BaseElement {
+    static readonly is = "ai-card-switch";
+    private _currentChecked;
+    protected render(): void;
+    updateProps(props: Record<string, any>, isMobile?: boolean): void;
+    private commit;
+    private escapeAttr;
+}
+
+declare class CardChoiceList extends BaseElement {
+    static readonly is = "ai-card-choice-list";
+    private _currentValue;
+    private readonly _onChoiceRequest;
+    private readonly _onChoiceNavigate;
+    protected render(): void;
+    updateProps(props: Record<string, any>, isMobile?: boolean): void;
+    private commitRequest;
+    private syncItems;
+    private navigateFrom;
+    private get mode();
+    private get currentValue();
+    private get values();
+    private get maxSelected();
+    private normalizeValue;
+    private cloneValue;
+    private escapeAttr;
+}
+
+interface IconRenderInput {
+    name?: unknown;
+    src?: unknown;
+    size?: unknown;
+    color?: unknown;
+}
+
+interface ChoiceItemSelectionContext {
+    selectionMode: 'single' | 'multiple';
+    variant: 'plain' | 'outlined';
+    selected: boolean;
+    listDisabled: boolean;
+    listReadonly: boolean;
+    selectionBlocked: boolean;
+    tabIndex: 0 | -1;
+    indicatorPosition: 'start' | 'end';
+    itemStyle?: Record<string, any>;
+    selectedItemStyle?: Record<string, any>;
+    indicatorStyle?: Record<string, any>;
+    selectedIndicatorStyle?: Record<string, any>;
+    checkedIcon?: IconRenderInput;
+}
+declare class CardChoiceItem extends BaseElement {
+    static readonly is = "ai-card-choice-item";
+    private _context;
+    get value(): string;
+    get itemDisabled(): boolean;
+    setSelectionContext(context: ChoiceItemSelectionContext): void;
+    focusIndicator(): void;
+    protected render(): void;
+    private renderIndicator;
+    private requestChange;
+    private hasInteractiveTarget;
+    private escapeAttr;
+}
+
 /**
  * Component Renderer Registry — maps schema `type` to render functions.
  *
@@ -1349,5 +1775,5 @@ declare const componentRenderers: Record<string, ComponentRenderer>;
  */
 declare function registerComponent(type: string, renderer: ComponentRenderer): void;
 
-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 };
-export type { A2UIActionPayload, BotSDKOptions, ButtonProps, CardInstance, CollapseProps, ComponentRenderer, ConnectorConfig, DividerProps, FormField, FormProps, HtmlProps, IconProps, ImageProps, InputProps, LoadingProps, PartialFinalizeResult, PasscodeInputProps, ProgressProps, ProgressSegment, RateProps, RenderCardOptions, SSEConnectOptions, SelectOption, SelectProps, StepIcon, StepItem, StepsProps, StreamingCardInstance, StreamingCardOptions, StreamingConnectOptions, StreamingConnection, 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, 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 };