@antglobal/copilot-cards-core 1.0.4 → 1.0.6

package/dist/validation-text.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Action Runner — executes ActionStep chains defined in card schemas.
+ *
+ * Supported action types:
+ * - **request**: HTTP request (fetch / API call)
+ * - **toast**: Display a toast notification
+ * - **url**: Navigate to a URL
+ * - **setVariable**: Update a variable in the card context
+ * - **emit**: Emit a custom event to the host environment
+ * - **copy**: Copy text to clipboard
+ *
+ * Each step can have `onSuccess` / `onFail` branches for chaining.
+ */
+interface ActionStep {
+    type: 'request' | 'emit' | 'url' | 'setVariable' | 'toast' | 'copy' | (string & {});
+    params: Record<string, any>;
+    /** Action chain to run on success (optional). */
+    onSuccess?: ActionStep[];
+    /** Action chain to run on failure (optional). */
+    onFail?: ActionStep[];
+}
+
+/**
+ * Legacy Schema Compatibility — converts old-format card JSON into
+ * the current CardSchema format so it can be rendered by the SDK.
+ *
+ * Old format:
+ * ```json
+ * {
+ *   "cardType": "common",
+ *   "cardContents": [{ "type": "text", "content": { "text": "hello" } }],
+ *   "text": "card text",
+ *   "extInfo": { "language": "zh-CN" }
+ * }
+ * ```
+ *
+ * Usage:
+ * ```ts
+ * import { convertLegacySchema } from '@antglobal/copilot-cards-core';
+ * const schema = convertLegacySchema(oldJson);
+ * renderCard(container, schema);
+ * ```
+ */
+
+type LegacyTrackingType = 'click' | 'expo';
+interface LegacyTracking {
+    spm: string;
+    type: LegacyTrackingType;
+}
+interface LegacyCardSchema {
+    cardType: 'common' | 'special' | string;
+    cardName?: string;
+    cardContents: LegacyCardContentItem[] | LegacyCardContentItem;
+    text: string;
+    extInfo: {
+        language: string;
+        [key: string]: any;
+    };
+    description?: string;
+    tracking?: LegacyTracking;
+}
+interface LegacyCardContentItem {
+    type: 'timeline' | 'button' | 'image' | 'form' | 'group' | 'text' | 'custom' | string;
+    groupInfo?: Record<string, any>;
+    content: Record<string, any>;
+}
+
+/**
+ * Schema Parser — resolves a CardSchema into a renderable tree.
+ *
+ * A CardSchema contains a flat `elements` map plus a `rootID` entry point,
+ * global `variables`, and optional global `actions`.
+ */
+
+/** Value that can be a static literal or a `${...}` expression. */
+interface ExpressionValue {
+    type: 'static' | 'expression';
+    value: string;
+}
+/**
+ * Slot layout mode — the key name in `props.slots` determines the layout:
+ * - default: no special layout, children appended directly
+ * - flex: one-dimensional Flexbox layout applied to the host container
+ * - columns: multi-column layout using groups (each group = one column)
+ * - grid: CSS grid with configurable column count and gap
+ * - horizontalScroll: horizontal scrollable container with drag and snap
+ * - carousel: center-focused carousel with scale/opacity effects
+ * - list: vertical list with optional ordered/unordered markers
+ * - float: relative container with absolutely positioned overlays
+ */
+type SlotLayout = 'default' | 'flex' | 'columns' | 'grid' | 'horizontalScroll' | 'carousel' | 'list' | 'float' | 'keyValue' | 'table' | 'chart';
+/** Binds a slot to a template that is instantiated once per source item. */
+interface RepeatBinding {
+    source: string;
+    template: string;
+    item?: string;
+    index?: string;
+    emptyTemplate?: string;
+}
+/**
+ * Content of a named slot.
+ *
+ * - `children`  — flat list of child element IDs (default, grid, horizontalScroll, carousel, list)
+ * - `groups`    — grouped child IDs, each sub-array is one region (columns)
+ * - `config`    — layout-specific parameters (grid columns, list style, float overlays, etc.)
+ *
+ * Grid `config` fields:
+ * - `columns`   — column count (default 2)
+ * - `gap`       — track gap (default '8px')
+ * - `rows`      — opt-in: explicit row count. When set, empty cells keep their
+ *                 height and children can be pinned to a cell via their own
+ *                 `style.gridColumn` / `style.gridRow`. Omit for auto-flow.
+ * - `rowHeight` — min height per row when `rows` is set (default '48px')
+ *
+ * Horizontal scroll `config` fields include:
+ * - `scrollbar` — `auto` leaves presentation to the host/browser, `hidden` hides
+ *                 the native scrollbar, and `visible` explicitly restores it.
+ *                 Omitted/invalid values preserve the legacy hidden output.
+ */
+interface SlotContent {
+    children?: string[];
+    groups?: string[][];
+    repeat?: RepeatBinding;
+    config?: Record<string, any>;
+}
+/** A single element inside the card. */
+interface ElementNode {
+    id: string;
+    type: string;
+    props: {
+        style?: Record<string, any>;
+        content?: ExpressionValue | string;
+        slots?: Partial<Record<SlotLayout, SlotContent>>;
+        [key: string]: any;
+    };
+    /** Lifecycle hooks — each is a chain of ActionSteps. */
+    lifecycle?: {
+        onMount?: ActionStep[];
+        onExposed?: ActionStep[];
+        onDestroy?: ActionStep[];
+    };
+    /** Interaction events — each is a chain of ActionSteps or a string reference to schema.actions. */
+    events?: {
+        onClick?: ActionStep[] | string;
+        onChange?: ActionStep[] | string;
+        onSubmit?: ActionStep[] | string;
+        [key: string]: ActionStep[] | string | undefined;
+    };
+    /** Directives that control visibility, disabled state, loops, etc. */
+    directives?: {
+        visible?: string;
+        /** Expression that resolves to truthy → element is disabled (greyed out, no events). */
+        disabled?: string;
+        [key: string]: any;
+    };
+}
+/** Top-level card schema handed to the SDK. */
+interface CardSchema {
+    version: string;
+    rootID: string;
+    elements: Record<string, ElementNode>;
+    variables: Record<string, any>;
+    /** Global action definitions reusable across elements. */
+    actions?: Record<string, ActionStep[]>;
+}
+/** Accepted input — either the current CardSchema or a legacy format. */
+type CardSchemaInput = CardSchema | LegacyCardSchema;
+type SchemaValidationIssueCode = 'SCHEMA_TYPE_MISMATCH' | 'SCHEMA_REQUIRED_FIELD' | 'LEGACY_CONVERSION_FAILED' | 'ROOT_TYPE_MISMATCH' | 'ROOT_REFERENCE_NOT_FOUND' | 'ELEMENTS_UNINSPECTABLE' | 'ELEMENT_ACCESSOR_NOT_ALLOWED' | 'ELEMENT_TYPE_MISMATCH' | 'ELEMENT_TYPE_MISSING' | 'ELEMENT_PROPS_TYPE_MISMATCH' | 'SLOTS_TYPE_MISMATCH' | 'SLOT_ACCESSOR_NOT_ALLOWED' | 'SLOTS_UNINSPECTABLE' | 'SLOT_TYPE_MISMATCH' | 'SLOT_CHILDREN_TYPE_MISMATCH' | 'SLOT_CHILD_ID_INVALID' | 'SLOT_GROUPS_TYPE_MISMATCH' | 'SLOT_GROUP_TYPE_MISMATCH' | 'SLOT_GROUP_CHILD_ID_INVALID' | 'ELEMENT_REFERENCE_NOT_FOUND' | 'DYNAMIC_SLOT_MULTIPLE' | 'DYNAMIC_TEMPLATE_INVALID' | 'DYNAMIC_TEMPLATE_NOT_FOUND' | 'REPEAT_TYPE_MISMATCH' | 'REPEAT_SLOT_UNSUPPORTED' | 'REPEAT_CONTENT_CONFLICT' | 'REPEAT_SOURCE_TYPE_MISMATCH' | 'REPEAT_SOURCE_INVALID' | 'REPEAT_TEMPLATE_TYPE_MISMATCH' | 'REPEAT_TEMPLATE_INVALID' | 'REPEAT_TEMPLATE_NOT_FOUND' | 'REPEAT_ALIAS_TYPE_MISMATCH' | 'REPEAT_ALIAS_INVALID' | 'REPEAT_ALIAS_RESERVED' | 'REPEAT_ALIAS_COLLISION' | 'REPEAT_EMPTY_TEMPLATE_TYPE_MISMATCH' | 'REPEAT_EMPTY_TEMPLATE_INVALID' | 'REPEAT_EMPTY_TEMPLATE_NOT_FOUND' | 'REPEAT_TEMPLATE_CYCLE' | 'DYNAMIC_TEMPLATE_CYCLE' | 'DYNAMIC_LIFECYCLE_UNSUPPORTED' | 'DYNAMIC_VARIABLE_KEY_UNSUPPORTED';
+
+/**
+ * Optional, editor-oriented validation for JSON source text.
+ *
+ * Kept out of the Core main entry so render-only consumers do not bundle a
+ * fault-tolerant JSON parser they never use.
+ */
+
+declare const SCHEMA_TEXT_MAX_CHARACTERS = 1000000;
+declare const SCHEMA_TEXT_MAX_DEPTH = 128;
+declare const SCHEMA_TEXT_MAX_ERRORS = 50;
+type SchemaTextValidationIssueCode = SchemaValidationIssueCode | 'JSON_SYNTAX_ERROR' | 'JSON_DUPLICATE_PROPERTY' | 'JSON_INPUT_TOO_LARGE' | 'JSON_MAX_DEPTH_EXCEEDED';
+interface SourcePosition {
+    /** 1-based source line. */
+    line: number;
+    /** 1-based UTF-16 source column. */
+    column: number;
+    /** 0-based UTF-16 source offset. */
+    offset: number;
+}
+interface SourceRange {
+    start: SourcePosition;
+    /** Exclusive end position. */
+    end: SourcePosition;
+}
+interface SchemaTextValidationIssue {
+    code: SchemaTextValidationIssueCode;
+    path: string;
+    anchorPath?: string;
+    message: string;
+    params?: Record<string, unknown>;
+    range: SourceRange;
+}
+type SchemaTextValidationResult = {
+    valid: true;
+    schema: CardSchemaInput;
+    errors: [];
+} | {
+    valid: false;
+    errors: SchemaTextValidationIssue[];
+    truncated: boolean;
+};
+/** Parse strict JSON and return syntax plus SDK-owned schema diagnostics. */
+declare function validateSchemaText(text: string): SchemaTextValidationResult;
+
+export { SCHEMA_TEXT_MAX_CHARACTERS, SCHEMA_TEXT_MAX_DEPTH, SCHEMA_TEXT_MAX_ERRORS, validateSchemaText };
+export type { SchemaTextValidationIssue, SchemaTextValidationIssueCode, SchemaTextValidationResult, SourcePosition, SourceRange };