@antglobal/copilot-cards-core 1.0.4 → 1.0.6

package/dist/index.d.ts

@@ -40,8 +40,8 @@ interface ActionRunnerContext {
     /** Optional adapter-specific resolver for structured parameter bindings. */
     parameterResolver?: (params: Record<string, any>) => Record<string, any>;
     /**
-     * Bound-renderer write hook. Static callers omit it and retain the existing
-     * direct-write plus setVariable behavior.
+     * Renderer-owned write hook. When present, it owns the synchronous variable
+     * write and decides whether that write should publish a render.
      */
     variableWriter?: (key: string, value: any, options: {
         silent: boolean;
@@ -151,6 +151,7 @@ interface ExpressionValue {
 /**
  * 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
@@ -158,13 +159,14 @@ interface ExpressionValue {
  * - list: vertical list with optional ordered/unordered markers
  * - float: relative container with absolutely positioned overlays
  */
-type SlotLayout = 'default' | 'columns' | 'grid' | 'horizontalScroll' | 'carousel' | 'list' | 'float' | 'keyValue' | 'table' | 'chart';
+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;
+    item?: string;
     index?: string;
+    emptyTemplate?: string;
 }
 /**
  * Content of a named slot.
@@ -180,6 +182,11 @@ interface RepeatBinding {
  *                 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[];
@@ -267,9 +274,27 @@ interface RenderTreeNode {
  * lists element IDs that become nested RenderTreeNodes.
  */
 declare function parseSchema(input: CardSchemaInput): RenderTreeNode;
+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';
+/** A machine-readable schema validation diagnostic. */
+interface SchemaValidationIssue {
+    code: SchemaValidationIssueCode;
+    /** RFC 6901 JSON Pointer to the invalid or missing value. */
+    path: string;
+    /** Existing parent used when `path` names a missing source value. */
+    anchorPath?: string;
+    /** Backwards-compatible, human-readable error text. */
+    message: string;
+    /** Dynamic values for localization or custom presentation. */
+    params?: Record<string, unknown>;
+}
 /**
- * Validate a CardSchema and return any error messages.
+ * Validate an unknown schema input and return structured diagnostics.
+ *
+ * Component names and component-specific props are deliberately not checked;
+ * this validator only owns the shared card graph and binding protocol.
  */
+declare function validateSchemaDetailed(input: unknown): SchemaValidationIssue[];
+/** Validate a CardSchema and return backwards-compatible error messages. */
 declare function validateSchema(input: CardSchemaInput): string[];
 
 /**
@@ -468,6 +493,7 @@ interface RepeatOwner {
     sourceOwnerId: string;
     slot: SlotLayout;
     templateId: string;
+    emptyTemplateId?: string;
     sourcePath?: string;
     dataPath: string;
     instancePath: string;
@@ -1430,5 +1456,5 @@ interface BuiltinIconDefinition {
 declare const BUILTIN_ICON_NAMES: readonly (keyof typeof BUILTIN_ICONS)[];
 declare function getBuiltinIcon(name: string | undefined): BuiltinIconDefinition | undefined;
 
-export { ActionRegistry, BUILTIN_ICONS, BUILTIN_ICON_NAMES, JsonPointerPathError, LifecycleManager, StreamingEngine, StreamingParser, a2uiComponentToElement, a2uiToCommand, bindingTopologyFingerprint, cloneJsonData, convertLegacySchema, createA2UIParameterResolver, createExpressionContext, createLifecycleManager, decodeJsonPointerSegment, extractPartialSchema, findAffectedRepeatOwners, findTemplateRepeatOwners, getBuiltinIcon, getByJsonPointer, getByPath, hasDynamicChildren, hasExpression, interpolate, isA2UIChildList, isA2UIDynamicChildList, isA2UIEnvelope, isA2UIPathBinding, isBoundRenderTreeNode, isLegacySchema, materializeCard, normalizeSchema, parseJsonPointer, parseSchema, registerActionHandler, registry, replaceRootContents, requiresBindingMaterialization, resetIdCounter, resolveA2UIDeep, resolveA2UIPath, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, setByJsonPointer, setByPath, validateSchema };
-export type { A2UIChildList, A2UIComponent, A2UIDynamicChildList, A2UIEnvelope, A2UIPathBinding, ActionChainConfig, ActionConfigProvider, ActionRunnerContext, ActionStep, ActionStepHandler, AppendContentCommand, BindingScope, BoundInstance, BoundRenderTreeNode, BuiltinIconDefinition, BuiltinIconName, CardSchema, CardSchemaInput, CleanupFn, ComponentChange, CreateSurfaceCommand, DeleteSurfaceCommand, ElementLifecycle, ElementNode, ExpressionContext, ExpressionValue, JsonPointerPathErrorCode, LegacyCardContentItem, LegacyCardSchema, LegacyTracking, LegacyTrackingType, MaterializeDiagnostic, MaterializeOptions, MaterializedCard, PartialSchemaResult, RenderTreeNode, RepeatBinding, RepeatOwner, SimpleActionHandler, SlotContent, SlotLayout, StreamingCommand, StreamingEngineEvents, StreamingParserOptions, UpdateComponentsCommand, UpdateDataModelCommand };
+export { ActionRegistry, BUILTIN_ICONS, BUILTIN_ICON_NAMES, JsonPointerPathError, LifecycleManager, StreamingEngine, StreamingParser, a2uiComponentToElement, a2uiToCommand, bindingTopologyFingerprint, cloneJsonData, convertLegacySchema, createA2UIParameterResolver, createExpressionContext, createLifecycleManager, decodeJsonPointerSegment, extractPartialSchema, findAffectedRepeatOwners, findTemplateRepeatOwners, getBuiltinIcon, getByJsonPointer, getByPath, hasDynamicChildren, hasExpression, interpolate, isA2UIChildList, isA2UIDynamicChildList, isA2UIEnvelope, isA2UIPathBinding, isBoundRenderTreeNode, isLegacySchema, materializeCard, normalizeSchema, parseJsonPointer, parseSchema, registerActionHandler, registry, replaceRootContents, requiresBindingMaterialization, resetIdCounter, resolveA2UIDeep, resolveA2UIPath, resolveActionRef, resolveDeep, resolveExpression, resolveExpressionValue, runActionStep, runActionSteps, setByJsonPointer, setByPath, validateSchema, validateSchemaDetailed };
+export type { A2UIChildList, A2UIComponent, A2UIDynamicChildList, A2UIEnvelope, A2UIPathBinding, ActionChainConfig, ActionConfigProvider, ActionRunnerContext, ActionStep, ActionStepHandler, AppendContentCommand, BindingScope, BoundInstance, BoundRenderTreeNode, BuiltinIconDefinition, BuiltinIconName, CardSchema, CardSchemaInput, CleanupFn, ComponentChange, CreateSurfaceCommand, DeleteSurfaceCommand, ElementLifecycle, ElementNode, ExpressionContext, ExpressionValue, JsonPointerPathErrorCode, LegacyCardContentItem, LegacyCardSchema, LegacyTracking, LegacyTrackingType, MaterializeDiagnostic, MaterializeOptions, MaterializedCard, PartialSchemaResult, RenderTreeNode, RepeatBinding, RepeatOwner, SchemaValidationIssue, SchemaValidationIssueCode, SimpleActionHandler, SlotContent, SlotLayout, StreamingCommand, StreamingEngineEvents, StreamingParserOptions, UpdateComponentsCommand, UpdateDataModelCommand };