@easyops-cn/a2ui-react 0.0.0 → 0.0.2

package/README.md

@@ -1,6 +1,4 @@
-# A2UI React Renderer Library
-
-https://easyops-cn.github.io/a2ui-react/
+# A2UI React Renderer
 
 A React renderer library for [A2UI](https://a2ui.org) protocol.
 
@@ -8,6 +6,8 @@ Supports all components in A2UI standard catalog out of the box. Built with [sha
 
 Currently A2UI protocol v0.8 is fully supported. Work on v0.9 is in progress.
 
+[Docs](https://easyops-cn.github.io/a2ui-react/) | [Playground](https://easyops-cn.github.io/a2ui-react/playground/)
+
 ## Installation
 
 ```sh
@@ -22,11 +22,11 @@ First, use the `@source` directive to tell Tailwind to scan the library code for
 @source "../node_modules/@easyops-cn/a2ui-react";
 ```
 
-Next, use the `A2UIRender` component to render A2UI messages:
+Next, use the `A2UIRenderer` component to render A2UI messages:
 
 ```tsx
 import {
-  A2UIRender,
+  A2UIRenderer,
   type A2UIMessage,
   type A2UIAction,
 } from '@easyops-cn/a2ui-react/0.8'
@@ -38,7 +38,7 @@ function App() {
     console.log('Action received:', action)
   }
 
-  return <A2UIRender messages={messages} onAction={handleAction} />
+  return <A2UIRenderer messages={messages} onAction={handleAction} />
 }
 ```
 
@@ -47,7 +47,11 @@ function App() {
 You can override default components or add new custom components via the `components` prop, which takes a `Map<string, React.ComponentType>`.
 
 ```tsx
-import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+import {
+  A2UIRenderer,
+  A2UIMessage,
+  A2UIAction,
+} from '@easyops-cn/a2ui-react/0.8'
 
 const ComponentsMap = new Map<string, React.ComponentType<any>>([
   // Override default Button component with a custom one
@@ -59,7 +63,7 @@ const ComponentsMap = new Map<string, React.ComponentType<any>>([
 
 function App() {
   return (
-    <A2UIRender
+    <A2UIRenderer
       components={ComponentsMap}
       messages={messages}
       onAction={handleAction}

package/dist/0.8/A2UIRenderer.d.ts

@@ -0,0 +1,49 @@
+import { ComponentType } from 'react';
+import { A2UIMessage, ActionPayload, BaseComponentProps } from './types';
+/**
+ * Type for custom component map.
+ */
+export type ComponentsMap = Map<string, ComponentType<BaseComponentProps & Record<string, unknown>>>;
+/**
+ * Props for A2UIRenderer component.
+ */
+export interface A2UIRenderProps {
+    /** Array of A2UI messages to render */
+    messages: A2UIMessage[];
+    /** Callback when an action is dispatched */
+    onAction?: (action: ActionPayload) => void;
+    /** Custom component overrides */
+    components?: ComponentsMap;
+}
+/**
+ * Main entry component for rendering A2UI messages.
+ *
+ * Processes an array of A2UIMessage objects and renders the resulting UI.
+ * Supports custom component overrides via the components prop.
+ *
+ * @param props - Component props
+ * @param props.messages - Array of A2UI messages to render
+ * @param props.onAction - Optional callback when an action is dispatched
+ * @param props.components - Optional custom component overrides
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <A2UIRenderer messages={messages} onAction={handleAction} />
+ *
+ * // With custom components
+ * const customComponents = new Map([
+ *   ['Button', CustomButton],
+ *   ['Switch', CustomSwitch],
+ * ])
+ * <A2UIRenderer
+ *   messages={messages}
+ *   onAction={handleAction}
+ *   components={customComponents}
+ * />
+ * ```
+ */
+export declare function A2UIRenderer({ messages, onAction, components, }: A2UIRenderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace A2UIRenderer {
+    var displayName: string;
+}

package/dist/0.8/A2UIRenderer.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A2UIRenderer Tests
+ *
+ * Tests for the main A2UIRenderer component.
+ */
+export {};

package/dist/0.8/components/ComponentRenderer.d.ts

@@ -0,0 +1,39 @@
+import { ComponentType } from 'react';
+import { BaseComponentProps } from '../types';
+/**
+ * Component registry mapping component type names to React components.
+ */
+export declare const componentRegistry: Record<string, ComponentType<BaseComponentProps & Record<string, unknown>>>;
+/**
+ * Props for ComponentRenderer.
+ */
+export interface ComponentRendererProps {
+    surfaceId: string;
+    componentId: string;
+}
+/**
+ * Renders a component based on its type from the component registry.
+ * Supports custom component overrides via ComponentsMapContext.
+ *
+ * @example
+ * ```tsx
+ * // Render a component by ID
+ * <ComponentRenderer surfaceId="surface-1" componentId="text-1" />
+ * ```
+ */
+export declare const ComponentRenderer: import('react').NamedExoticComponent<ComponentRendererProps>;
+/**
+ * Registers a custom component type.
+ *
+ * @param type - The component type name
+ * @param component - The React component to register
+ *
+ * @example
+ * ```tsx
+ * registerComponent('CustomChart', ({ surfaceId, data }) => {
+ *   const chartData = useDataBinding(surfaceId, data, []);
+ *   return <Chart data={chartData} />;
+ * });
+ * ```
+ */
+export declare function registerComponent(type: string, component: ComponentType<BaseComponentProps & Record<string, unknown>>): void;

package/dist/0.8/components/ComponentRenderer.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * ComponentRenderer Tests
+ *
+ * Tests for the ComponentRenderer component that routes rendering based on type.
+ */
+export {};

package/dist/0.8/components/UnknownComponent.d.ts

@@ -0,0 +1,18 @@
+import { BaseComponentProps } from '../types';
+/**
+ * Props for UnknownComponent.
+ */
+export interface UnknownComponentProps extends BaseComponentProps {
+    /** The unknown component type name */
+    componentType: string;
+}
+/**
+ * Placeholder component for unknown types in development mode.
+ *
+ * Displays a warning box with the unknown component type name
+ * to help developers identify configuration issues.
+ */
+export declare function UnknownComponent({ componentId, componentType, }: UnknownComponentProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace UnknownComponent {
+    var displayName: string;
+}

package/dist/0.8/components/display/AudioPlayerComponent.d.ts

@@ -0,0 +1,5 @@
+import { AudioPlayerComponentProps } from '../../types';
+/**
+ * AudioPlayer component for playing audio content.
+ */
+export declare const AudioPlayerComponent: import('react').NamedExoticComponent<AudioPlayerComponentProps>;

package/dist/0.8/components/display/DividerComponent.d.ts

@@ -0,0 +1,5 @@
+import { DividerComponentProps } from '../../types';
+/**
+ * Divider component for visual separation.
+ */
+export declare const DividerComponent: import('react').NamedExoticComponent<DividerComponentProps>;

package/dist/0.8/components/display/IconComponent.d.ts

@@ -0,0 +1,5 @@
+import { IconComponentProps } from '../../types';
+/**
+ * Icon component for displaying icons from the A2UI icon set.
+ */
+export declare const IconComponent: import('react').NamedExoticComponent<IconComponentProps>;

package/dist/0.8/components/display/ImageComponent.d.ts

@@ -0,0 +1,6 @@
+import { ImageComponentProps } from '../../types';
+/**
+ * Image component for displaying images.
+ * Supports different sizes via usageHint and object-fit via fit property.
+ */
+export declare const ImageComponent: import('react').NamedExoticComponent<ImageComponentProps>;

package/dist/0.8/components/display/TextComponent.d.ts

@@ -0,0 +1,6 @@
+import { TextComponentProps } from '../../types';
+/**
+ * Text component for displaying text content.
+ * Supports basic Markdown formatting and different text styles via usageHint.
+ */
+export declare const TextComponent: import('react').NamedExoticComponent<TextComponentProps>;

package/dist/0.8/components/display/VideoComponent.d.ts

@@ -0,0 +1,5 @@
+import { VideoComponentProps } from '../../types';
+/**
+ * Video component for displaying video content.
+ */
+export declare const VideoComponent: import('react').NamedExoticComponent<VideoComponentProps>;

package/dist/0.8/components/display/display.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Display Components Tests
+ *
+ * Tests for TextComponent, ImageComponent, IconComponent, VideoComponent,
+ * AudioPlayerComponent, and DividerComponent.
+ */
+export {};

package/dist/0.8/components/display/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A2UI React Renderer - Display Components
+ */
+export { TextComponent } from './TextComponent';
+export { ImageComponent } from './ImageComponent';
+export { IconComponent } from './IconComponent';
+export { VideoComponent } from './VideoComponent';
+export { AudioPlayerComponent } from './AudioPlayerComponent';
+export { DividerComponent } from './DividerComponent';

package/dist/0.8/components/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A2UI React Renderer - Components Exports
+ */
+export { ComponentRenderer, registerComponent } from './ComponentRenderer';
+export * from './display';
+export * from './layout';
+export * from './interactive';

package/dist/0.8/components/interactive/ButtonComponent.d.ts

@@ -0,0 +1,5 @@
+import { ButtonComponentProps } from '../../types';
+/**
+ * Button component - triggers actions on click.
+ */
+export declare const ButtonComponent: import('react').NamedExoticComponent<ButtonComponentProps>;

package/dist/0.8/components/interactive/CheckBoxComponent.d.ts

@@ -0,0 +1,5 @@
+import { CheckBoxComponentProps } from '../../types';
+/**
+ * CheckBox component - checkbox input with label.
+ */
+export declare const CheckBoxComponent: import('react').NamedExoticComponent<CheckBoxComponentProps>;

package/dist/0.8/components/interactive/DateTimeInputComponent.d.ts

@@ -0,0 +1,5 @@
+import { DateTimeInputComponentProps } from '../../types';
+/**
+ * DateTimeInput component - date/time picker using Calendar and Popover.
+ */
+export declare const DateTimeInputComponent: import('react').NamedExoticComponent<DateTimeInputComponentProps>;

package/dist/0.8/components/interactive/MultipleChoiceComponent.d.ts

@@ -0,0 +1,7 @@
+import { MultipleChoiceComponentProps } from '../../types';
+/**
+ * MultipleChoice component - dropdown/select input.
+ * When maxAllowedSelections === 1, renders as a dropdown.
+ * When maxAllowedSelections > 1 or undefined, renders as checkboxes for multi-select.
+ */
+export declare const MultipleChoiceComponent: import('react').NamedExoticComponent<MultipleChoiceComponentProps>;

package/dist/0.8/components/interactive/SliderComponent.d.ts

@@ -0,0 +1,5 @@
+import { SliderComponentProps } from '../../types';
+/**
+ * Slider component - range slider input.
+ */
+export declare const SliderComponent: import('react').NamedExoticComponent<SliderComponentProps>;

package/dist/0.8/components/interactive/TextFieldComponent.d.ts

@@ -0,0 +1,5 @@
+import { TextFieldComponentProps } from '../../types';
+/**
+ * TextField component - text input with label.
+ */
+export declare const TextFieldComponent: import('react').NamedExoticComponent<TextFieldComponentProps>;

package/dist/0.8/components/interactive/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A2UI React Renderer - Interactive Components
+ */
+export { ButtonComponent } from './ButtonComponent';
+export { CheckBoxComponent } from './CheckBoxComponent';
+export { TextFieldComponent } from './TextFieldComponent';
+export { DateTimeInputComponent } from './DateTimeInputComponent';
+export { MultipleChoiceComponent } from './MultipleChoiceComponent';
+export { SliderComponent } from './SliderComponent';

package/dist/0.8/components/interactive/interactive.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Interactive Components Tests
+ *
+ * Tests for ButtonComponent, CheckBoxComponent, TextFieldComponent,
+ * DateTimeInputComponent, MultipleChoiceComponent, and SliderComponent.
+ */
+export {};

package/dist/0.8/components/layout/CardComponent.d.ts

@@ -0,0 +1,5 @@
+import { CardComponentProps } from '../../types';
+/**
+ * Card component - container with card styling.
+ */
+export declare const CardComponent: import('react').NamedExoticComponent<CardComponentProps>;

package/dist/0.8/components/layout/ColumnComponent.d.ts

@@ -0,0 +1,5 @@
+import { ColumnComponentProps } from '../../types';
+/**
+ * Column component - vertical flex container.
+ */
+export declare const ColumnComponent: import('react').NamedExoticComponent<ColumnComponentProps>;

package/dist/0.8/components/layout/ListComponent.d.ts

@@ -0,0 +1,5 @@
+import { ListComponentProps } from '../../types';
+/**
+ * List component - container for list items.
+ */
+export declare const ListComponent: import('react').NamedExoticComponent<ListComponentProps>;

package/dist/0.8/components/layout/ModalComponent.d.ts

@@ -0,0 +1,5 @@
+import { ModalComponentProps } from '../../types';
+/**
+ * Modal component - dialog container with trigger.
+ */
+export declare const ModalComponent: import('react').NamedExoticComponent<ModalComponentProps>;

package/dist/0.8/components/layout/RowComponent.d.ts

@@ -0,0 +1,5 @@
+import { RowComponentProps } from '../../types';
+/**
+ * Row component - horizontal flex container.
+ */
+export declare const RowComponent: import('react').NamedExoticComponent<RowComponentProps>;

package/dist/0.8/components/layout/TabsComponent.d.ts

@@ -0,0 +1,5 @@
+import { TabsComponentProps } from '../../types';
+/**
+ * Tabs component - tabbed content container.
+ */
+export declare const TabsComponent: import('react').NamedExoticComponent<TabsComponentProps>;

package/dist/0.8/components/layout/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A2UI React Renderer - Layout Components
+ */
+export { RowComponent } from './RowComponent';
+export { ColumnComponent } from './ColumnComponent';
+export { ListComponent } from './ListComponent';
+export { CardComponent } from './CardComponent';
+export { TabsComponent } from './TabsComponent';
+export { ModalComponent } from './ModalComponent';

package/dist/0.8/components/layout/layout.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Layout Components Tests
+ *
+ * Tests for RowComponent, ColumnComponent, ListComponent, CardComponent,
+ * TabsComponent, and ModalComponent.
+ */
+export {};

package/dist/0.8/contexts/A2UIProvider.d.ts

@@ -0,0 +1,34 @@
+import { ReactNode } from 'react';
+import { ActionHandler } from '../types';
+/**
+ * Props for A2UIProvider.
+ */
+export interface A2UIProviderProps {
+    /** Callback when an action is dispatched */
+    onAction?: ActionHandler;
+    children: ReactNode;
+}
+/**
+ * Combined provider for all A2UI contexts.
+ *
+ * Provides:
+ * - SurfaceContext: Component tree management
+ * - DataModelContext: Data model state
+ * - ActionContext: Action dispatching
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const handleAction = (action) => {
+ *     console.log('Action:', action);
+ *   };
+ *
+ *   return (
+ *     <A2UIProvider onAction={handleAction}>
+ *       <A2UIReactRenderer messages={messages} />
+ *     </A2UIProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function A2UIProvider({ onAction, children }: A2UIProviderProps): import("react/jsx-runtime").JSX.Element;

package/dist/0.8/contexts/A2UIProvider.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A2UIProvider Tests
+ *
+ * Tests for the combined A2UI provider component.
+ */
+export {};

package/dist/0.8/contexts/ActionContext.d.ts

@@ -0,0 +1,33 @@
+import { ReactNode } from 'react';
+import { Action, ActionHandler } from '../types';
+/**
+ * Action context value interface.
+ */
+export interface ActionContextValue {
+    /** Dispatches an action with resolved context */
+    dispatchAction: (surfaceId: string, componentId: string, action: Action) => void;
+    /** The action handler callback (if set) */
+    onAction: ActionHandler | null;
+}
+/**
+ * Action context for A2UI rendering.
+ */
+export declare const ActionContext: import('react').Context<ActionContextValue | null>;
+/**
+ * Props for ActionProvider.
+ */
+export interface ActionProviderProps {
+    /** Callback when an action is dispatched */
+    onAction?: ActionHandler;
+    children: ReactNode;
+}
+/**
+ * Provider component for Action dispatching.
+ */
+export declare function ActionProvider({ onAction, children }: ActionProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the Action context.
+ *
+ * @throws Error if used outside of ActionProvider
+ */
+export declare function useActionContext(): ActionContextValue;

package/dist/0.8/contexts/ActionContext.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * ActionContext Tests
+ *
+ * Tests for the Action context provider and hook.
+ */
+export {};

package/dist/0.8/contexts/ComponentsMapContext.d.ts

@@ -0,0 +1,63 @@
+import { ReactNode, ComponentType } from 'react';
+import { BaseComponentProps } from '../types';
+/**
+ * Type for a component in the components map.
+ */
+export type A2UIComponent = ComponentType<BaseComponentProps & Record<string, unknown>>;
+/**
+ * Map of component type names to React components.
+ */
+export type ComponentsMap = Map<string, A2UIComponent>;
+/**
+ * Context value for ComponentsMapContext.
+ */
+export interface ComponentsMapContextValue {
+    /** Custom components provided by the user */
+    customComponents: ComponentsMap;
+    /** Get a component by type name (custom first, then default) */
+    getComponent: (type: string) => A2UIComponent | undefined;
+}
+/**
+ * Context for custom component overrides.
+ */
+export declare const ComponentsMapContext: import('react').Context<ComponentsMapContextValue | null>;
+/**
+ * Props for ComponentsMapProvider.
+ */
+export interface ComponentsMapProviderProps {
+    /** Custom components to override or extend defaults */
+    components?: ComponentsMap;
+    /** Default component registry */
+    defaultComponents: Record<string, A2UIComponent>;
+    children: ReactNode;
+}
+/**
+ * Provider for custom component overrides.
+ *
+ * @example
+ * ```tsx
+ * const customComponents = new Map([
+ *   ['Button', CustomButton],
+ *   ['Switch', CustomSwitch],
+ * ])
+ *
+ * <ComponentsMapProvider components={customComponents} defaultComponents={defaultRegistry}>
+ *   <App />
+ * </ComponentsMapProvider>
+ * ```
+ */
+export declare function ComponentsMapProvider({ components, defaultComponents, children, }: ComponentsMapProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the ComponentsMap context.
+ *
+ * @throws Error if used outside of ComponentsMapProvider
+ */
+export declare function useComponentsMapContext(): ComponentsMapContextValue;
+/**
+ * Hook to get a component by type name.
+ * Returns custom component if available, otherwise default.
+ *
+ * @param type - The component type name
+ * @returns The component or undefined if not found
+ */
+export declare function useComponentFromMap(type: string): A2UIComponent | undefined;

package/dist/0.8/contexts/DataModelContext.d.ts

@@ -0,0 +1,43 @@
+import { ReactNode } from 'react';
+import { DataModel, DataModelValue } from '../types';
+/**
+ * DataModel context value interface.
+ */
+export interface DataModelContextValue {
+    /** Map of data models by surfaceId */
+    dataModels: Map<string, DataModel>;
+    /** Updates the data model at a path with merge behavior */
+    updateDataModel: (surfaceId: string, path: string, data: Record<string, unknown>) => void;
+    /** Gets a value from the data model */
+    getDataValue: (surfaceId: string, path: string) => DataModelValue | undefined;
+    /** Sets a value in the data model (used by form inputs) */
+    setDataValue: (surfaceId: string, path: string, value: unknown) => void;
+    /** Gets the entire data model for a surface */
+    getDataModel: (surfaceId: string) => DataModel;
+    /** Initializes the data model for a surface */
+    initDataModel: (surfaceId: string) => void;
+    /** Deletes the data model for a surface */
+    deleteDataModel: (surfaceId: string) => void;
+    /** Clears all data models */
+    clearDataModels: () => void;
+}
+/**
+ * DataModel context for A2UI rendering.
+ */
+export declare const DataModelContext: import('react').Context<DataModelContextValue | null>;
+/**
+ * Props for DataModelProvider.
+ */
+export interface DataModelProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provider component for DataModel state management.
+ */
+export declare function DataModelProvider({ children }: DataModelProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the DataModel context.
+ *
+ * @throws Error if used outside of DataModelProvider
+ */
+export declare function useDataModelContext(): DataModelContextValue;

package/dist/0.8/contexts/DataModelContext.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * DataModelContext Tests
+ *
+ * Tests for the DataModel context provider and hook.
+ */
+export {};

package/dist/0.8/contexts/SurfaceContext.d.ts

@@ -0,0 +1,45 @@
+import { ReactNode } from 'react';
+import { Surface, ComponentDefinition, SurfaceStyles } from '../types';
+/**
+ * Surface context value interface.
+ */
+export interface SurfaceContextValue {
+    /** Map of all surfaces by surfaceId */
+    surfaces: Map<string, Surface>;
+    /**
+     * Initializes a surface with root and styles.
+     * If the surface already exists, preserves existing components.
+     * Called when beginRendering message is received.
+     */
+    initSurface: (surfaceId: string, root: string, styles?: SurfaceStyles) => void;
+    /** Updates components in a surface */
+    updateSurface: (surfaceId: string, components: ComponentDefinition[]) => void;
+    /** Deletes a surface */
+    deleteSurface: (surfaceId: string) => void;
+    /** Gets a surface by ID */
+    getSurface: (surfaceId: string) => Surface | undefined;
+    /** Gets a component from a surface */
+    getComponent: (surfaceId: string, componentId: string) => ComponentDefinition | undefined;
+    /** Clears all surfaces */
+    clearSurfaces: () => void;
+}
+/**
+ * Surface context for A2UI rendering.
+ */
+export declare const SurfaceContext: import('react').Context<SurfaceContextValue | null>;
+/**
+ * Props for SurfaceProvider.
+ */
+export interface SurfaceProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provider component for Surface state management.
+ */
+export declare function SurfaceProvider({ children }: SurfaceProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the Surface context.
+ *
+ * @throws Error if used outside of SurfaceProvider
+ */
+export declare function useSurfaceContext(): SurfaceContextValue;

package/dist/0.8/contexts/SurfaceContext.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SurfaceContext Tests
+ *
+ * Tests for the Surface context provider and hook.
+ */
+export {};