@a2ui-sdk/types 0.0.0

package/dist/0.8/index.d.ts

@@ -0,0 +1,316 @@
+/**
+ * A2UI React Renderer - Type Definitions
+ *
+ * Core type definitions for the A2UI React renderer.
+ * Based on the A2UI specification documents.
+ */
+/**
+ * Represents a value source - either a literal value or a reference to a data model path.
+ */
+export type ValueSource = {
+    literalString: string;
+} | {
+    literalNumber: number;
+} | {
+    literalBoolean: boolean;
+} | {
+    literalArray: string[];
+} | {
+    path: string;
+};
+/**
+ * Primitive values that can be stored in the data model.
+ */
+export type DataModelValue = string | number | boolean | null | DataModel | unknown[];
+/**
+ * The data model is a hierarchical key-value store.
+ * Components reference data using paths like "/user/name".
+ */
+export interface DataModel {
+    [key: string]: DataModelValue;
+}
+/**
+ * Data entry from server messages (dataModelUpdate).
+ */
+export interface DataEntry {
+    key: string;
+    valueString?: string;
+    valueNumber?: number;
+    valueBoolean?: boolean;
+    valueMap?: DataEntry[];
+}
+/**
+ * Surface styles configuration.
+ */
+export interface SurfaceStyles {
+    font?: string;
+    primaryColor?: string;
+}
+/**
+ * A Surface is the top-level container for A2UI rendering.
+ */
+export interface Surface {
+    surfaceId: string;
+    root: string;
+    components: Map<string, ComponentDefinition>;
+    styles?: SurfaceStyles;
+}
+/**
+ * Base component properties that all components share.
+ */
+export interface ComponentDefinition {
+    id: string;
+    weight?: number;
+    component: {
+        [componentType: string]: ComponentProps;
+    };
+}
+/**
+ * Generic component properties type.
+ */
+export type ComponentProps = Record<string, unknown>;
+/**
+ * Template binding for dynamic child generation.
+ */
+export interface TemplateBinding {
+    componentId: string;
+    dataBinding: string;
+}
+/**
+ * Children definition for container components.
+ */
+export interface ChildrenDefinition {
+    explicitList?: string[];
+    template?: TemplateBinding;
+}
+/**
+ * A single item in the action context.
+ */
+export interface ActionContextItem {
+    key: string;
+    value: ValueSource;
+}
+/**
+ * Action definition (attached to Button components).
+ */
+export interface Action {
+    name: string;
+    context?: ActionContextItem[];
+}
+/**
+ * Resolved action payload sent to the action handler.
+ */
+export interface ActionPayload {
+    surfaceId: string;
+    name: string;
+    context: Record<string, unknown>;
+    sourceComponentId: string;
+}
+/**
+ * Action handler callback type.
+ */
+export type ActionHandler = (action: ActionPayload) => void;
+/**
+ * BeginRendering message payload - initializes a new Surface.
+ */
+export interface BeginRenderingPayload {
+    surfaceId: string;
+    root: string;
+    catalogId?: string;
+    styles?: SurfaceStyles;
+}
+/**
+ * SurfaceUpdate message payload - updates the component tree.
+ */
+export interface SurfaceUpdatePayload {
+    surfaceId: string;
+    components: ComponentDefinition[];
+}
+/**
+ * DataModelUpdate message payload - updates the data model.
+ */
+export interface DataModelUpdatePayload {
+    surfaceId: string;
+    path?: string;
+    contents: DataEntry[];
+}
+/**
+ * DeleteSurface message payload - removes a Surface.
+ */
+export interface DeleteSurfacePayload {
+    surfaceId: string;
+}
+/**
+ * A2UI message from server to client.
+ * Only one of the fields should be set per message.
+ */
+export interface A2UIMessage {
+    beginRendering?: BeginRenderingPayload;
+    surfaceUpdate?: SurfaceUpdatePayload;
+    dataModelUpdate?: DataModelUpdatePayload;
+    deleteSurface?: DeleteSurfacePayload;
+}
+/**
+ * Base props shared by all A2UI components.
+ */
+export interface BaseComponentProps {
+    surfaceId: string;
+    componentId: string;
+    weight?: number;
+}
+/**
+ * Text component properties.
+ */
+export interface TextComponentProps extends BaseComponentProps {
+    text?: ValueSource;
+    usageHint?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'caption' | 'body';
+}
+/**
+ * Image component properties.
+ */
+export interface ImageComponentProps extends BaseComponentProps {
+    url?: ValueSource;
+    fit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    usageHint?: 'icon' | 'avatar' | 'smallFeature' | 'mediumFeature' | 'largeFeature' | 'header';
+}
+/**
+ * Icon component properties.
+ */
+export interface IconComponentProps extends BaseComponentProps {
+    name?: ValueSource;
+}
+/**
+ * Video component properties.
+ */
+export interface VideoComponentProps extends BaseComponentProps {
+    url?: ValueSource;
+}
+/**
+ * AudioPlayer component properties.
+ */
+export interface AudioPlayerComponentProps extends BaseComponentProps {
+    url?: ValueSource;
+    description?: ValueSource;
+}
+/**
+ * Divider component properties.
+ */
+export interface DividerComponentProps extends BaseComponentProps {
+    axis?: 'horizontal' | 'vertical';
+}
+/**
+ * Distribution values for flex layouts.
+ */
+export type Distribution = 'start' | 'center' | 'end' | 'spaceBetween' | 'spaceAround' | 'spaceEvenly';
+/**
+ * Alignment values for flex layouts.
+ */
+export type Alignment = 'start' | 'center' | 'end' | 'stretch';
+/**
+ * Row component properties.
+ */
+export interface RowComponentProps extends BaseComponentProps {
+    children?: ChildrenDefinition;
+    distribution?: Distribution;
+    alignment?: Alignment;
+}
+/**
+ * Column component properties.
+ */
+export interface ColumnComponentProps extends BaseComponentProps {
+    children?: ChildrenDefinition;
+    distribution?: Distribution;
+    alignment?: Alignment;
+}
+/**
+ * List component properties.
+ */
+export interface ListComponentProps extends BaseComponentProps {
+    children?: ChildrenDefinition;
+    direction?: 'vertical' | 'horizontal';
+    alignment?: Alignment;
+}
+/**
+ * Card component properties.
+ */
+export interface CardComponentProps extends BaseComponentProps {
+    child?: string;
+}
+/**
+ * Tab item definition.
+ */
+export interface TabItem {
+    title?: ValueSource;
+    child: string;
+}
+/**
+ * Tabs component properties.
+ */
+export interface TabsComponentProps extends BaseComponentProps {
+    tabItems?: TabItem[];
+}
+/**
+ * Modal component properties.
+ */
+export interface ModalComponentProps extends BaseComponentProps {
+    entryPointChild?: string;
+    contentChild?: string;
+}
+/**
+ * Button component properties.
+ */
+export interface ButtonComponentProps extends BaseComponentProps {
+    child?: string;
+    primary?: boolean;
+    action?: Action;
+}
+/**
+ * CheckBox component properties.
+ */
+export interface CheckBoxComponentProps extends BaseComponentProps {
+    label?: ValueSource;
+    value?: ValueSource;
+}
+/**
+ * TextField component properties.
+ */
+export interface TextFieldComponentProps extends BaseComponentProps {
+    label?: ValueSource;
+    text?: ValueSource;
+    textFieldType?: 'date' | 'longText' | 'number' | 'shortText' | 'obscured';
+    validationRegexp?: string;
+}
+/**
+ * DateTimeInput component properties.
+ */
+export interface DateTimeInputComponentProps extends BaseComponentProps {
+    label?: ValueSource;
+    value?: ValueSource;
+    enableDate?: boolean;
+    enableTime?: boolean;
+}
+/**
+ * MultipleChoice option definition.
+ */
+export interface MultipleChoiceOption {
+    label?: ValueSource;
+    value: string;
+}
+/**
+ * MultipleChoice component properties.
+ */
+export interface MultipleChoiceComponentProps extends BaseComponentProps {
+    label?: ValueSource;
+    selections?: ValueSource;
+    options?: MultipleChoiceOption[];
+    maxAllowedSelections?: number;
+}
+/**
+ * Slider component properties.
+ */
+export interface SliderComponentProps extends BaseComponentProps {
+    label?: ValueSource;
+    value?: ValueSource;
+    minValue?: number;
+    maxValue?: number;
+}

package/dist/0.8/index.js

@@ -0,0 +1,7 @@
+/**
+ * A2UI React Renderer - Type Definitions
+ *
+ * Core type definitions for the A2UI React renderer.
+ * Based on the A2UI specification documents.
+ */
+export {};

package/dist/0.9/index.d.ts

@@ -0,0 +1,391 @@
+/**
+ * A2UI 0.9 React Renderer - Type Definitions
+ *
+ * Core type definitions for the A2UI 0.9 React renderer.
+ * Based on the A2UI 0.9 protocol specification.
+ */
+/**
+ * A2UI message from server to client.
+ * Each message contains exactly one of the four message types.
+ */
+export type A2UIMessage = {
+    createSurface: CreateSurfacePayload;
+} | {
+    updateComponents: UpdateComponentsPayload;
+} | {
+    updateDataModel: UpdateDataModelPayload;
+} | {
+    deleteSurface: DeleteSurfacePayload;
+};
+/**
+ * CreateSurface message payload - initializes a new Surface.
+ */
+export interface CreateSurfacePayload {
+    surfaceId: string;
+    catalogId: string;
+}
+/**
+ * UpdateComponents message payload - adds/updates components in the surface's component tree.
+ */
+export interface UpdateComponentsPayload {
+    surfaceId: string;
+    components: Component[];
+}
+/**
+ * UpdateDataModel message payload - updates the data model at a specific path.
+ */
+export interface UpdateDataModelPayload {
+    surfaceId: string;
+    /** JSON Pointer path (RFC 6901), defaults to "/" (root) */
+    path?: string;
+    /** If omitted, data at path is removed */
+    value?: unknown;
+}
+/**
+ * DeleteSurface message payload - removes a Surface.
+ */
+export interface DeleteSurfacePayload {
+    surfaceId: string;
+}
+/**
+ * A function call expression.
+ */
+export interface FunctionCall {
+    call: string;
+    args?: Record<string, DynamicValue>;
+    returnType?: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'any';
+}
+/**
+ * Logic expression for boolean evaluation.
+ */
+export type LogicExpression = {
+    and: LogicExpression[];
+} | {
+    or: LogicExpression[];
+} | {
+    not: LogicExpression;
+} | FunctionCall | {
+    true: true;
+} | {
+    false: false;
+};
+/**
+ * Generic dynamic value (any type).
+ */
+export type DynamicValue = string | number | boolean | {
+    path: string;
+} | FunctionCall;
+/**
+ * Dynamic string value.
+ */
+export type DynamicString = string | {
+    path: string;
+} | FunctionCall;
+/**
+ * Dynamic number value.
+ */
+export type DynamicNumber = number | {
+    path: string;
+} | FunctionCall;
+/**
+ * Dynamic boolean value.
+ */
+export type DynamicBoolean = boolean | {
+    path: string;
+} | LogicExpression;
+/**
+ * Dynamic string list value.
+ */
+export type DynamicStringList = string[] | {
+    path: string;
+} | FunctionCall;
+/**
+ * Union of all bindable value types (for form binding hooks).
+ * Used by useFormBinding to accept any dynamic value type.
+ */
+export type FormBindableValue = DynamicValue | DynamicString | DynamicNumber | DynamicBoolean | DynamicStringList;
+/**
+ * Template binding for dynamic child generation.
+ */
+export interface TemplateBinding {
+    componentId: string;
+    path: string;
+}
+/**
+ * Children definition for container components.
+ */
+export type ChildList = string[] | TemplateBinding;
+/**
+ * Check rule for validation.
+ */
+export interface CheckRule {
+    message: string;
+    call?: string;
+    args?: Record<string, DynamicValue>;
+    and?: CheckRule[];
+    or?: CheckRule[];
+    not?: CheckRule;
+    true?: true;
+    false?: false;
+}
+/**
+ * Mixin interface for components that support validation checks.
+ */
+export interface Checkable {
+    checks?: CheckRule[];
+}
+/**
+ * Base component properties that all components share.
+ */
+export interface ComponentBase {
+    id: string;
+    /** Discriminator: "Text", "Button", etc. */
+    component: string;
+    /** flex-grow for Row/Column children */
+    weight?: number;
+}
+/**
+ * Text component.
+ */
+export interface TextComponent extends ComponentBase {
+    component: 'Text';
+    text: DynamicString;
+    variant?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'caption' | 'body';
+}
+/**
+ * Image component.
+ */
+export interface ImageComponent extends ComponentBase {
+    component: 'Image';
+    url: DynamicString;
+    fit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    variant?: 'icon' | 'avatar' | 'smallFeature' | 'mediumFeature' | 'largeFeature' | 'header';
+}
+/**
+ * Icon component.
+ */
+export interface IconComponent extends ComponentBase {
+    component: 'Icon';
+    name: DynamicString;
+}
+/**
+ * Video component.
+ */
+export interface VideoComponent extends ComponentBase {
+    component: 'Video';
+    url: DynamicString;
+}
+/**
+ * AudioPlayer component.
+ */
+export interface AudioPlayerComponent extends ComponentBase {
+    component: 'AudioPlayer';
+    url: DynamicString;
+    description?: DynamicString;
+}
+/**
+ * Divider component.
+ */
+export interface DividerComponent extends ComponentBase {
+    component: 'Divider';
+    axis?: 'horizontal' | 'vertical';
+}
+/**
+ * Justify values for flex layouts (main axis distribution).
+ */
+export type Justify = 'start' | 'center' | 'end' | 'spaceBetween' | 'spaceAround' | 'spaceEvenly' | 'stretch';
+/**
+ * Align values for flex layouts (cross axis alignment).
+ */
+export type Align = 'start' | 'center' | 'end' | 'stretch';
+/**
+ * Row component.
+ */
+export interface RowComponent extends ComponentBase {
+    component: 'Row';
+    children: ChildList;
+    justify?: Justify;
+    align?: Align;
+}
+/**
+ * Column component.
+ */
+export interface ColumnComponent extends ComponentBase {
+    component: 'Column';
+    children: ChildList;
+    justify?: Justify;
+    align?: Align;
+}
+/**
+ * List component.
+ */
+export interface ListComponent extends ComponentBase {
+    component: 'List';
+    children: ChildList;
+    direction?: 'vertical' | 'horizontal';
+    align?: Align;
+}
+/**
+ * Card component.
+ */
+export interface CardComponent extends ComponentBase {
+    component: 'Card';
+    /** Single child component ID */
+    child: string;
+}
+/**
+ * Tab item definition.
+ */
+export interface TabItem {
+    title: DynamicString;
+    /** Component ID */
+    child: string;
+}
+/**
+ * Tabs component.
+ */
+export interface TabsComponent extends ComponentBase {
+    component: 'Tabs';
+    tabs: TabItem[];
+}
+/**
+ * Modal component.
+ */
+export interface ModalComponent extends ComponentBase {
+    component: 'Modal';
+    /** Component ID for trigger */
+    trigger: string;
+    /** Component ID for content */
+    content: string;
+}
+/**
+ * Action definition (attached to Button components).
+ */
+export interface Action {
+    name: string;
+    context?: Record<string, DynamicValue>;
+}
+/**
+ * Button component.
+ */
+export interface ButtonComponent extends ComponentBase, Checkable {
+    component: 'Button';
+    /** Component ID (typically Text or Icon) */
+    child: string;
+    primary?: boolean;
+    action: Action;
+}
+/**
+ * TextField component.
+ */
+export interface TextFieldComponent extends ComponentBase, Checkable {
+    component: 'TextField';
+    label: DynamicString;
+    /** Two-way binding path */
+    value?: DynamicString;
+    variant?: 'longText' | 'number' | 'shortText' | 'obscured';
+}
+/**
+ * CheckBox component.
+ */
+export interface CheckBoxComponent extends ComponentBase, Checkable {
+    component: 'CheckBox';
+    label: DynamicString;
+    /** Two-way binding path */
+    value: DynamicBoolean;
+}
+/**
+ * Choice option definition.
+ */
+export interface ChoiceOption {
+    label: DynamicString;
+    value: string;
+}
+/**
+ * ChoicePicker component (renamed from MultipleChoice).
+ */
+export interface ChoicePickerComponent extends ComponentBase, Checkable {
+    component: 'ChoicePicker';
+    label?: DynamicString;
+    variant?: 'multipleSelection' | 'mutuallyExclusive';
+    options: ChoiceOption[];
+    /** Two-way binding path */
+    value: DynamicStringList;
+}
+/**
+ * Slider component.
+ */
+export interface SliderComponent extends ComponentBase, Checkable {
+    component: 'Slider';
+    label?: DynamicString;
+    min: number;
+    max: number;
+    /** Two-way binding path */
+    value: DynamicNumber;
+}
+/**
+ * DateTimeInput component.
+ */
+export interface DateTimeInputComponent extends ComponentBase, Checkable {
+    component: 'DateTimeInput';
+    /** Two-way binding path (ISO 8601) */
+    value: DynamicString;
+    enableDate?: boolean;
+    enableTime?: boolean;
+    outputFormat?: string;
+    label?: DynamicString;
+}
+/**
+ * Union type of all standard catalog components.
+ */
+export type Component = TextComponent | ImageComponent | IconComponent | VideoComponent | AudioPlayerComponent | DividerComponent | RowComponent | ColumnComponent | ListComponent | CardComponent | TabsComponent | ModalComponent | ButtonComponent | TextFieldComponent | CheckBoxComponent | ChoicePickerComponent | SliderComponent | DateTimeInputComponent;
+/**
+ * Data model type (hierarchical key-value store).
+ */
+export type DataModel = Record<string, unknown>;
+/**
+ * Surface state.
+ */
+export interface SurfaceState {
+    surfaceId: string;
+    catalogId: string;
+    components: Map<string, Component>;
+    dataModel: DataModel;
+    created: boolean;
+}
+/**
+ * Provider state managing multiple surfaces.
+ */
+export interface ProviderState {
+    surfaces: Map<string, SurfaceState>;
+    messageBuffer: Map<string, A2UIMessage[]>;
+}
+/**
+ * Scope value for collection scopes.
+ */
+export interface ScopeValue {
+    /** null = root scope, otherwise the base path for relative resolution */
+    basePath: string | null;
+}
+/**
+ * Validation result.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    /** List of failed check messages */
+    errors: string[];
+}
+/**
+ * Resolved action payload sent to the action handler.
+ */
+export interface ActionPayload {
+    name: string;
+    surfaceId: string;
+    sourceComponentId: string;
+    timestamp: string;
+    context: Record<string, unknown>;
+}
+/**
+ * Action handler callback type.
+ */
+export type ActionHandler = (action: ActionPayload) => void;

package/dist/0.9/index.js

@@ -0,0 +1,7 @@
+/**
+ * A2UI 0.9 React Renderer - Type Definitions
+ *
+ * Core type definitions for the A2UI 0.9 React renderer.
+ * Based on the A2UI 0.9 protocol specification.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * as v0_8 from './0.8/index.js';
+export * as v0_9 from './0.9/index.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * as v0_8 from './0.8/index.js';
+export * as v0_9 from './0.9/index.js';

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/index.ts","../src/0.8/index.ts","../src/0.9/index.ts"],"version":"5.9.3"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@a2ui-sdk/types",
+  "version": "0.0.0",
+  "description": "A2UI types",
+  "homepage": "https://easyops-cn.github.io/a2ui-sdk/",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:easyops-cn/a2ui-sdk.git",
+    "directory": "packages/types"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./0.8": {
+      "types": "./dist/0.8/index.d.ts",
+      "default": "./dist/0.8/index.js"
+    },
+    "./0.9": {
+      "types": "./dist/0.9/index.d.ts",
+      "default": "./dist/0.9/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsc -b --watch",
+    "build": "tsc -b"
+  },
+  "license": "Apache-2.0"
+}