@datalayer/agent-runtimes 1.0.2 → 1.0.3

package/lib/examples/A2UiContactCardExample.js

@@ -0,0 +1,432 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A2UiContactCardExample
+ *
+ * Demonstrates a rich contact card UI rendered via A2UI protocol.
+ * Uses static A2UI JSON messages (no backend required) featuring:
+ * - Data-bound contact information (name, title, email, phone, etc.)
+ * - Avatar image with cover fit
+ * - Icon + text info rows (calendar, location, email, phone)
+ * - Interactive buttons with actions (Follow, Message)
+ * - Card and Column layout composition
+ * - Divider for visual separation
+ *
+ * Based on the contact_lookup sample from the A2UI repository.
+ */
+import { useState, useCallback } from 'react';
+import { Box } from '@datalayer/primer-addons';
+import { ThemedProvider } from './utils/themedProvider';
+import { Text, Button as PrimerButton } from '@primer/react';
+import { A2UIProvider, A2UIRenderer, useA2UIActions, initializeDefaultCatalog, } from '@a2ui/react';
+initializeDefaultCatalog();
+const CONTACTS = [
+    {
+        name: 'Alice Johnson',
+        title: 'Staff Engineer',
+        team: 'Platform',
+        location: 'San Francisco, CA',
+        email: 'alice@example.com',
+        mobile: '+1 (415) 555-0101',
+        calendar: 'Available',
+        imageUrl: 'https://api.dicebear.com/9.x/avataaars/svg?seed=Alice',
+    },
+    {
+        name: 'Bob Martinez',
+        title: 'Product Manager',
+        team: 'Growth',
+        location: 'New York, NY',
+        email: 'bob@example.com',
+        mobile: '+1 (212) 555-0202',
+        calendar: 'In a meeting',
+        imageUrl: 'https://api.dicebear.com/9.x/avataaars/svg?seed=Bob',
+    },
+    {
+        name: 'Casey Smith',
+        title: 'Digital Marketing Specialist',
+        team: 'Marketing',
+        location: 'London, UK',
+        email: 'casey@example.com',
+        mobile: '+44 20 7946 0958',
+        calendar: 'Out of office',
+        imageUrl: 'https://api.dicebear.com/9.x/avataaars/svg?seed=Casey',
+    },
+];
+// ---------------------------------------------------------------------------
+// A2UI message builders
+// ---------------------------------------------------------------------------
+function contactCardMessages(contact) {
+    return [
+        // Begin rendering
+        { beginRendering: { surfaceId: 'contact-card', root: 'main_card' } },
+        // Surface update - component tree
+        {
+            surfaceUpdate: {
+                surfaceId: 'contact-card',
+                components: [
+                    {
+                        id: 'profile_image',
+                        component: {
+                            Image: {
+                                url: { path: '/imageUrl' },
+                                usageHint: 'avatar',
+                                fit: 'cover',
+                            },
+                        },
+                    },
+                    {
+                        id: 'user_heading',
+                        weight: 1,
+                        component: { Text: { text: { path: '/name' }, usageHint: 'h2' } },
+                    },
+                    {
+                        id: 'description_text_1',
+                        component: { Text: { text: { path: '/title' } } },
+                    },
+                    {
+                        id: 'description_text_2',
+                        component: { Text: { text: { path: '/team' } } },
+                    },
+                    {
+                        id: 'description_column',
+                        component: {
+                            Column: {
+                                children: {
+                                    explicitList: [
+                                        'user_heading',
+                                        'description_text_1',
+                                        'description_text_2',
+                                    ],
+                                },
+                                alignment: 'center',
+                            },
+                        },
+                    },
+                    // Calendar row
+                    {
+                        id: 'calendar_icon',
+                        component: { Icon: { name: { literalString: 'calendar_today' } } },
+                    },
+                    {
+                        id: 'calendar_primary_text',
+                        component: {
+                            Text: { usageHint: 'h5', text: { path: '/calendar' } },
+                        },
+                    },
+                    {
+                        id: 'calendar_secondary_text',
+                        component: { Text: { text: { literalString: 'Calendar' } } },
+                    },
+                    {
+                        id: 'calendar_text_column',
+                        component: {
+                            Column: {
+                                children: {
+                                    explicitList: [
+                                        'calendar_primary_text',
+                                        'calendar_secondary_text',
+                                    ],
+                                },
+                                distribution: 'start',
+                                alignment: 'start',
+                            },
+                        },
+                    },
+                    {
+                        id: 'info_row_1',
+                        component: {
+                            Row: {
+                                children: {
+                                    explicitList: ['calendar_icon', 'calendar_text_column'],
+                                },
+                                distribution: 'start',
+                                alignment: 'start',
+                            },
+                        },
+                    },
+                    // Location row
+                    {
+                        id: 'location_icon',
+                        component: { Icon: { name: { literalString: 'location_on' } } },
+                    },
+                    {
+                        id: 'location_primary_text',
+                        component: {
+                            Text: { usageHint: 'h5', text: { path: '/location' } },
+                        },
+                    },
+                    {
+                        id: 'location_secondary_text',
+                        component: { Text: { text: { literalString: 'Location' } } },
+                    },
+                    {
+                        id: 'location_text_column',
+                        component: {
+                            Column: {
+                                children: {
+                                    explicitList: [
+                                        'location_primary_text',
+                                        'location_secondary_text',
+                                    ],
+                                },
+                                distribution: 'start',
+                                alignment: 'start',
+                            },
+                        },
+                    },
+                    {
+                        id: 'info_row_2',
+                        component: {
+                            Row: {
+                                children: {
+                                    explicitList: ['location_icon', 'location_text_column'],
+                                },
+                                distribution: 'start',
+                                alignment: 'start',
+                            },
+                        },
+                    },
+                    // Email row
+                    {
+                        id: 'mail_icon',
+                        component: { Icon: { name: { literalString: 'mail' } } },
+                    },
+                    {
+                        id: 'mail_primary_text',
+                        component: { Text: { usageHint: 'h5', text: { path: '/email' } } },
+                    },
+                    {
+                        id: 'mail_secondary_text',
+                        component: { Text: { text: { literalString: 'Email' } } },
+                    },
+                    {
+                        id: 'mail_text_column',
+                        component: {
+                            Column: {
+                                children: {
+                                    explicitList: ['mail_primary_text', 'mail_secondary_text'],
+                                },
+                                distribution: 'start',
+                                alignment: 'start',
+                            },
+                        },
+                    },
+                    {
+                        id: 'info_row_3',
+                        component: {
+                            Row: {
+                                children: { explicitList: ['mail_icon', 'mail_text_column'] },
+                                distribution: 'start',
+                                alignment: 'start',
+                            },
+                        },
+                    },
+                    // Divider
+                    { id: 'div', component: { Divider: {} } },
+                    // Phone row
+                    {
+                        id: 'call_icon',
+                        component: { Icon: { name: { literalString: 'call' } } },
+                    },
+                    {
+                        id: 'call_primary_text',
+                        component: { Text: { usageHint: 'h5', text: { path: '/mobile' } } },
+                    },
+                    {
+                        id: 'call_secondary_text',
+                        component: { Text: { text: { literalString: 'Mobile' } } },
+                    },
+                    {
+                        id: 'call_text_column',
+                        component: {
+                            Column: {
+                                children: {
+                                    explicitList: ['call_primary_text', 'call_secondary_text'],
+                                },
+                                distribution: 'start',
+                                alignment: 'start',
+                            },
+                        },
+                    },
+                    {
+                        id: 'info_row_4',
+                        component: {
+                            Row: {
+                                children: { explicitList: ['call_icon', 'call_text_column'] },
+                                distribution: 'start',
+                                alignment: 'start',
+                            },
+                        },
+                    },
+                    // Info column
+                    {
+                        id: 'info_rows_column',
+                        weight: 1,
+                        component: {
+                            Column: {
+                                children: {
+                                    explicitList: [
+                                        'info_row_1',
+                                        'info_row_2',
+                                        'info_row_3',
+                                        'info_row_4',
+                                    ],
+                                },
+                                alignment: 'stretch',
+                            },
+                        },
+                    },
+                    // Action buttons
+                    {
+                        id: 'button_1_text',
+                        component: { Text: { text: { literalString: 'Follow' } } },
+                    },
+                    {
+                        id: 'button_1',
+                        component: {
+                            Button: {
+                                child: 'button_1_text',
+                                primary: true,
+                                action: {
+                                    name: 'follow_contact',
+                                    context: [{ key: 'contactName', value: { path: '/name' } }],
+                                },
+                            },
+                        },
+                    },
+                    {
+                        id: 'button_2_text',
+                        component: { Text: { text: { literalString: 'Message' } } },
+                    },
+                    {
+                        id: 'button_2',
+                        component: {
+                            Button: {
+                                child: 'button_2_text',
+                                primary: false,
+                                action: {
+                                    name: 'send_message',
+                                    context: [{ key: 'contactName', value: { path: '/name' } }],
+                                },
+                            },
+                        },
+                    },
+                    {
+                        id: 'action_buttons_row',
+                        component: {
+                            Row: {
+                                children: { explicitList: ['button_1', 'button_2'] },
+                                distribution: 'center',
+                                alignment: 'center',
+                            },
+                        },
+                    },
+                    // Main layout
+                    {
+                        id: 'main_column',
+                        component: {
+                            Column: {
+                                children: {
+                                    explicitList: [
+                                        'profile_image',
+                                        'description_column',
+                                        'div',
+                                        'info_rows_column',
+                                        'action_buttons_row',
+                                    ],
+                                },
+                                alignment: 'stretch',
+                            },
+                        },
+                    },
+                    { id: 'main_card', component: { Card: { child: 'main_column' } } },
+                ],
+            },
+        },
+        // Data model
+        {
+            dataModelUpdate: {
+                surfaceId: 'contact-card',
+                path: '/',
+                contents: [
+                    { key: 'name', valueString: contact.name },
+                    { key: 'title', valueString: contact.title },
+                    { key: 'team', valueString: contact.team },
+                    { key: 'location', valueString: contact.location },
+                    { key: 'email', valueString: contact.email },
+                    { key: 'mobile', valueString: contact.mobile },
+                    { key: 'calendar', valueString: contact.calendar },
+                    { key: 'imageUrl', valueString: contact.imageUrl },
+                ],
+            },
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// Components
+// ---------------------------------------------------------------------------
+function ContactCardContent() {
+    const { processMessages, clearSurfaces, getSurfaces } = useA2UIActions();
+    const [selectedIdx, setSelectedIdx] = useState(null);
+    const loadContact = useCallback((idx) => {
+        clearSurfaces();
+        processMessages(contactCardMessages(CONTACTS[idx]));
+        setSelectedIdx(idx);
+    }, [processMessages, clearSurfaces]);
+    const surfaces = getSurfaces();
+    const surfaceEntries = Array.from(surfaces.entries());
+    return (_jsxs(Box, { sx: { display: 'flex', flex: 1, overflow: 'hidden' }, children: [_jsxs(Box, { sx: {
+                    width: '260px',
+                    borderRight: '1px solid',
+                    borderColor: 'border.default',
+                    backgroundColor: 'canvas.subtle',
+                    padding: 3,
+                    display: 'flex',
+                    flexDirection: 'column',
+                    gap: 2,
+                }, children: [_jsx(Text, { as: "h3", sx: { fontSize: '1rem', fontWeight: 'bold', marginBottom: 2 }, children: "Contacts" }), CONTACTS.map((contact, idx) => (_jsx(PrimerButton, { variant: selectedIdx === idx ? 'primary' : 'default', onClick: () => loadContact(idx), sx: { width: '100%', justifyContent: 'flex-start' }, children: _jsxs(Box, { sx: {
+                                display: 'flex',
+                                flexDirection: 'column',
+                                alignItems: 'flex-start',
+                            }, children: [_jsx(Text, { sx: { fontWeight: 'bold', fontSize: '0.875rem' }, children: contact.name }), _jsx(Text, { sx: {
+                                        fontSize: '0.75rem',
+                                        color: selectedIdx === idx ? 'fg.onEmphasis' : 'fg.muted',
+                                    }, children: contact.title })] }) }, contact.email)))] }), _jsx(Box, { sx: {
+                    flex: 1,
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    padding: 4,
+                }, children: selectedIdx === null ? (_jsxs(Box, { sx: { textAlign: 'center' }, children: [_jsx(Text, { sx: { fontSize: '3rem' }, children: "\uD83D\uDC64" }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', marginTop: 2 }, children: "Select a contact from the sidebar" })] })) : (_jsx(Box, { sx: { maxWidth: '420px', width: '100%' }, children: surfaceEntries.map(([surfaceId]) => (_jsx(A2UIRenderer, { surfaceId: surfaceId }, surfaceId))) })) })] }));
+}
+/**
+ * A2UiContactCardExample — Rich contact card with data binding & actions.
+ * No backend required — uses static A2UI JSON messages rendered client-side.
+ */
+const A2UiContactCardExample = () => {
+    const handleAction = useCallback((actionMessage) => {
+        console.log('Contact action:', actionMessage);
+        alert(`Action: ${JSON.stringify(actionMessage, null, 2)}`);
+    }, []);
+    return (_jsx(ThemedProvider, { children: _jsx(A2UIProvider, { onAction: handleAction, children: _jsxs(Box, { sx: {
+                    display: 'flex',
+                    flexDirection: 'column',
+                    minHeight: '100vh',
+                    backgroundColor: 'canvas.default',
+                }, children: [_jsxs(Box, { sx: {
+                            padding: 3,
+                            borderBottom: '1px solid',
+                            borderColor: 'border.default',
+                            backgroundColor: 'canvas.subtle',
+                        }, children: [_jsx(Text, { as: "h1", sx: {
+                                    fontSize: '1.25rem',
+                                    fontWeight: 'bold',
+                                    display: 'flex',
+                                    alignItems: 'center',
+                                    gap: 2,
+                                }, children: "\uD83D\uDC64 A2UI Contact Card" }), _jsx(Text, { sx: { fontSize: '0.875rem', color: 'fg.muted' }, children: "Data-bound contact card with actions \u2014 based on A2UI contact_lookup sample" })] }), _jsx(ContactCardContent, {})] }) }) }));
+};
+export default A2UiContactCardExample;

package/lib/examples/A2UiRestaurantExample.d.ts

@@ -2,13 +2,16 @@
  * A2UiRestaurantExample
  *
  * Demonstrates A2UI (Agent-to-UI) protocol integration with a pydantic-ai
- * restaurant finder agent. The agent generates A2UI JSON messages that are
- * rendered into React components.
+ * restaurant finder agent using the official @a2ui/react renderer.
+ *
+ * The agent generates A2UI JSON messages that are rendered into
+ * interactive React components via A2UIProvider + A2UIRenderer.
  *
  * Features:
- * - A2UI protocol message processing
+ * - A2UI protocol message processing via @a2ui/react
  * - Dynamic UI generation from agent responses
  * - Restaurant search and booking interface
+ * - Action handling for interactive components (buttons, forms)
  * - Dark/light theme support
  *
  * Backend: /api/v1/a2ui/restaurant/
@@ -20,6 +23,11 @@ import React from 'react';
  * Demonstrates A2UI protocol integration with pydantic-ai.
  * The agent generates A2UI JSON messages for restaurant search,
  * display, and booking functionality.
+ *
+ * Uses @a2ui/react's two-context architecture:
+ * - A2UIProvider wraps the app, receives an onAction callback
+ * - useA2UIActions() provides processMessages/clearSurfaces/getSurfaces
+ * - A2UIRenderer renders surfaces by ID
  */
 declare const A2UiRestaurantExample: React.FC;
 export default A2UiRestaurantExample;