@zhama/a2ui-core 0.1.0

package/README.md

@@ -0,0 +1,161 @@
+# @zhama/a2ui-core
+
+A2UI Protocol Core Library - Framework-agnostic TypeScript types and builders for A2UI protocol.
+
+## Overview
+
+A2UI (Agent to UI) is a JSON-based streaming UI protocol for dynamically rendering user interfaces. This library provides:
+
+- **Types**: Complete TypeScript type definitions for A2UI v0.8 and v0.9
+- **Builders**: Convenient functions to build messages and components
+- **Validators**: Message validation utilities
+
+## Installation
+
+```bash
+npm install @zhama/a2ui-core
+# or
+pnpm add @zhama/a2ui-core
+```
+
+## Quick Start
+
+```typescript
+import {
+  // Builders
+  text, column, button, card,
+  createSurface, updateComponents, updateDataModel,
+  createV09Messages,
+  
+  // Validators
+  validateMessage,
+  
+  // Utils
+  path, generateId,
+  
+  // Types
+  type ComponentInstance,
+  type ServerToClientMessage,
+} from '@zhama/a2ui-core';
+
+// Create components
+const title = text('Hello World', { id: 'title', usageHint: 'h1' });
+const greeting = text({ path: '/user/name' }, { id: 'greeting' });
+const root = column(['title', 'greeting'], { id: 'root' });
+
+// Create messages
+const messages = createV09Messages({
+  surfaceId: 'my-surface',
+  components: [title, greeting, root],
+  dataModel: { user: { name: 'John' } },
+});
+
+// Validate messages
+const result = validateMessage(messages[0]);
+console.log(result.valid); // true
+```
+
+## API Reference
+
+### Types
+
+#### Primitives
+- `StringOrPath` - String literal or data path binding
+- `NumberOrPath` - Number literal or data path binding
+- `BooleanOrPath` - Boolean literal or data path binding
+
+#### Components
+- `TextComponent`, `ImageComponent`, `IconComponent`, `VideoComponent`, `AudioPlayerComponent`
+- `RowComponent`, `ColumnComponent`, `ListComponent`, `CardComponent`
+- `TabsComponent`, `DividerComponent`, `ModalComponent`
+- `ButtonComponent`, `CheckBoxComponent`, `TextFieldComponent`
+- `DateTimeInputComponent`, `ChoicePickerComponent`, `SliderComponent`
+
+#### Messages
+- `CreateSurfaceMessage`, `UpdateComponentsMessage`, `UpdateDataModelMessage`, `DeleteSurfaceMessage` (v0.9)
+- `BeginRenderingMessage`, `SurfaceUpdateMessage`, `DataModelUpdateMessage` (v0.8)
+
+### Builders
+
+#### Component Builders
+```typescript
+// Content components
+text(content: StringOrPath, options?: TextOptions): ComponentInstance
+image(url: StringOrPath, options?: ImageOptions): ComponentInstance
+icon(name: StringOrPath, options?: IconOptions): ComponentInstance
+
+// Layout components
+row(children: ChildrenProperty, options?: LayoutOptions): ComponentInstance
+column(children: ChildrenProperty, options?: LayoutOptions): ComponentInstance
+card(childId: string, options?: CardOptions): ComponentInstance
+
+// Interactive components
+button(childId: string, action: Action, options?: ButtonOptions): ComponentInstance
+textField(label: StringOrPath, text?: StringOrPath, options?: TextFieldOptions): ComponentInstance
+
+// Convenience
+textButton(buttonText: string, action: Action, options?: ButtonOptions): [ComponentInstance, ComponentInstance]
+h1(content: StringOrPath, options?: TextOptions): ComponentInstance
+```
+
+#### Message Builders
+```typescript
+// v0.9
+createSurface(surfaceId: string, catalogId?: string): CreateSurfaceMessage
+updateComponents(surfaceId: string, components: ComponentInstance[]): UpdateComponentsMessage
+updateDataModel(surfaceId: string, value: unknown, path?: string): UpdateDataModelMessage
+deleteSurface(surfaceId: string): DeleteSurfaceMessage
+createV09Messages(options: CreateV09Options): ServerToClientMessageV09[]
+
+// v0.8
+beginRendering(rootId: string, surfaceId?: string, styles?: Record<string, string>): BeginRenderingMessage
+surfaceUpdate(components: ComponentInstanceV08[], surfaceId?: string): SurfaceUpdateMessage
+dataModelUpdate(contents: ValueMap[], surfaceId?: string): DataModelUpdateMessage
+createV08Messages(options: CreateV08Options): ServerToClientMessageV08[]
+
+// Utilities
+messagesToJsonl(messages: ServerToClientMessage[]): string
+jsonlToMessages(jsonl: string): ServerToClientMessage[]
+```
+
+#### Data Model Builders
+```typescript
+objectToValueMap(obj: DataObject): ValueMap[]
+valueToValueMap(key: string, value: DataValue): ValueMap
+valueMapToObject(valueMaps: ValueMap[]): DataObject
+```
+
+### Validators
+
+```typescript
+validateMessage(message: ServerToClientMessage, options?: ValidationOptions): ValidationResult
+validateMessages(messages: ServerToClientMessage[], options?: ValidationOptions): ValidationResult
+```
+
+### Utils
+
+```typescript
+path(dataPath: string): { path: string }  // Create data binding
+isPathBinding(value): boolean             // Check if value is a path binding
+generateId(prefix?: string): string       // Generate unique ID
+uuid(): string                            // Generate UUID v4
+```
+
+## Protocol Versions
+
+### v0.9 (Prompt-first)
+- `createSurface` - Create a new surface
+- `updateComponents` - Update components with flat component list
+- `updateDataModel` - Update data model
+- `deleteSurface` - Delete surface
+
+### v0.8 (Structured output)
+- `beginRendering` - Signal to begin rendering
+- `surfaceUpdate` - Update components
+- `dataModelUpdate` - Update data model using ValueMap format
+- `deleteSurface` - Delete surface
+
+## License
+
+MIT
+

package/dist/builders/index.cjs

@@ -0,0 +1,496 @@
+'use strict';
+
+// src/builders/id-generator.ts
+var componentIdCounter = 0;
+function generateId(prefix = "comp") {
+  return `${prefix}_${Date.now()}_${componentIdCounter++}`;
+}
+function resetIdCounter() {
+  componentIdCounter = 0;
+}
+function getIdCounter() {
+  return componentIdCounter;
+}
+
+// src/builders/component-builder.ts
+function text(content, options = {}) {
+  const { id = generateId("text"), weight, usageHint } = options;
+  return {
+    id,
+    component: "Text",
+    text: content,
+    ...weight !== void 0 && { weight },
+    ...usageHint && { usageHint }
+  };
+}
+function image(url, options = {}) {
+  const { id = generateId("image"), weight, fit, usageHint } = options;
+  return {
+    id,
+    component: "Image",
+    url,
+    ...weight !== void 0 && { weight },
+    ...fit && { fit },
+    ...usageHint && { usageHint }
+  };
+}
+function icon(name, options = {}) {
+  const { id = generateId("icon"), weight } = options;
+  return {
+    id,
+    component: "Icon",
+    name,
+    ...weight !== void 0 && { weight }
+  };
+}
+function video(url, options = {}) {
+  const { id = generateId("video"), weight } = options;
+  return {
+    id,
+    component: "Video",
+    url,
+    ...weight !== void 0 && { weight }
+  };
+}
+function audioPlayer(url, options = {}) {
+  const { id = generateId("audio"), weight, description } = options;
+  return {
+    id,
+    component: "AudioPlayer",
+    url,
+    ...weight !== void 0 && { weight },
+    ...description && { description }
+  };
+}
+function row(children, options = {}) {
+  const { id = generateId("row"), weight, alignment, distribution } = options;
+  return {
+    id,
+    component: "Row",
+    children,
+    ...weight !== void 0 && { weight },
+    ...alignment && { alignment },
+    ...distribution && { distribution }
+  };
+}
+function column(children, options = {}) {
+  const { id = generateId("column"), weight, alignment, distribution } = options;
+  return {
+    id,
+    component: "Column",
+    children,
+    ...weight !== void 0 && { weight },
+    ...alignment && { alignment },
+    ...distribution && { distribution }
+  };
+}
+function list(children, options = {}) {
+  const { id = generateId("list"), weight, direction, alignment } = options;
+  return {
+    id,
+    component: "List",
+    children,
+    ...weight !== void 0 && { weight },
+    ...direction && { direction },
+    ...alignment && { alignment }
+  };
+}
+function card(childId, options = {}) {
+  const { id = generateId("card"), weight } = options;
+  return {
+    id,
+    component: "Card",
+    child: childId,
+    ...weight !== void 0 && { weight }
+  };
+}
+function tabs(items, options = {}) {
+  const { id = generateId("tabs"), weight } = options;
+  return {
+    id,
+    component: "Tabs",
+    tabItems: items.map((item) => ({
+      title: item.title,
+      child: item.childId
+    })),
+    ...weight !== void 0 && { weight }
+  };
+}
+function divider(options = {}) {
+  const { id = generateId("divider"), weight, axis } = options;
+  return {
+    id,
+    component: "Divider",
+    ...weight !== void 0 && { weight },
+    ...axis && { axis }
+  };
+}
+function modal(entryPointChildId, contentChildId, options = {}) {
+  const { id = generateId("modal"), weight } = options;
+  return {
+    id,
+    component: "Modal",
+    entryPointChild: entryPointChildId,
+    contentChild: contentChildId,
+    ...weight !== void 0 && { weight }
+  };
+}
+function button(childId, action, options = {}) {
+  const { id = generateId("button"), weight, primary } = options;
+  return {
+    id,
+    component: "Button",
+    child: childId,
+    action,
+    ...weight !== void 0 && { weight },
+    ...primary !== void 0 && { primary }
+  };
+}
+function checkbox(label, value, options = {}) {
+  const { id = generateId("checkbox"), weight } = options;
+  return {
+    id,
+    component: "CheckBox",
+    label,
+    value,
+    ...weight !== void 0 && { weight }
+  };
+}
+function textField(label, textValue, options = {}) {
+  const { id = generateId("textfield"), weight, usageHint, validationRegexp } = options;
+  return {
+    id,
+    component: "TextField",
+    label,
+    ...textValue !== void 0 && { text: textValue },
+    ...weight !== void 0 && { weight },
+    ...usageHint && { usageHint },
+    ...validationRegexp && { validationRegexp }
+  };
+}
+function dateTimeInput(value, options = {}) {
+  const { id = generateId("datetime"), weight, enableDate, enableTime, outputFormat, label } = options;
+  return {
+    id,
+    component: "DateTimeInput",
+    value,
+    ...weight !== void 0 && { weight },
+    ...enableDate !== void 0 && { enableDate },
+    ...enableTime !== void 0 && { enableTime },
+    ...outputFormat && { outputFormat },
+    ...label && { label }
+  };
+}
+function choicePicker(optionsList, value, usageHint, options = {}) {
+  const { id = generateId("choice"), weight, label } = options;
+  return {
+    id,
+    component: "ChoicePicker",
+    options: optionsList,
+    value,
+    usageHint,
+    ...weight !== void 0 && { weight },
+    ...label && { label }
+  };
+}
+function slider(value, options = {}) {
+  const { id = generateId("slider"), weight, label, min, max } = options;
+  return {
+    id,
+    component: "Slider",
+    value,
+    ...weight !== void 0 && { weight },
+    ...label && { label },
+    ...min !== void 0 && { min },
+    ...max !== void 0 && { max }
+  };
+}
+function textButton(buttonText, action, options = {}) {
+  const textId = options.textId ?? generateId("btn_text");
+  const textComp = text(buttonText, { id: textId });
+  const buttonComp = button(textId, action, options);
+  return [textComp, buttonComp];
+}
+function h1(content, options = {}) {
+  return text(content, { ...options, usageHint: "h1" });
+}
+function h2(content, options = {}) {
+  return text(content, { ...options, usageHint: "h2" });
+}
+function h3(content, options = {}) {
+  return text(content, { ...options, usageHint: "h3" });
+}
+function h4(content, options = {}) {
+  return text(content, { ...options, usageHint: "h4" });
+}
+function h5(content, options = {}) {
+  return text(content, { ...options, usageHint: "h5" });
+}
+function caption(content, options = {}) {
+  return text(content, { ...options, usageHint: "caption" });
+}
+function body(content, options = {}) {
+  return text(content, { ...options, usageHint: "body" });
+}
+
+// src/types/messages.ts
+var STANDARD_CATALOG_ID = "https://a2ui.dev/specification/0.9/standard_catalog_definition.json";
+
+// src/builders/data-model-builder.ts
+var DEFAULT_PATH_MAPPINGS = {};
+function objectToValueMap(obj, prefix = "") {
+  const entries = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}/${key}` : `/${key}`;
+    entries.push(valueToValueMap(fullKey, value));
+  }
+  return entries;
+}
+function valueToValueMap(key, value) {
+  if (value === null || value === void 0) {
+    return { key, valueString: "" };
+  }
+  if (typeof value === "string") {
+    return { key, valueString: value };
+  }
+  if (typeof value === "number") {
+    return { key, valueNumber: value };
+  }
+  if (typeof value === "boolean") {
+    return { key, valueBoolean: value };
+  }
+  if (Array.isArray(value)) {
+    return {
+      key,
+      valueMap: value.map((item, index) => valueToValueMap(String(index), item))
+    };
+  }
+  if (typeof value === "object") {
+    const nestedMaps = [];
+    for (const [k, v] of Object.entries(value)) {
+      nestedMaps.push(valueToValueMap(k, v));
+    }
+    return { key, valueMap: nestedMaps };
+  }
+  return { key, valueString: String(value) };
+}
+function normalizePath(path, pathMappings = {}) {
+  let normalizedPath = path.replace(/\./g, "/");
+  if (!normalizedPath.startsWith("/")) {
+    normalizedPath = `/${normalizedPath}`;
+  }
+  for (const [from, to] of Object.entries(pathMappings)) {
+    const fromPattern = new RegExp(`^/${from}(/|$)`);
+    if (fromPattern.test(normalizedPath)) {
+      normalizedPath = normalizedPath.replace(fromPattern, `/${to}$1`);
+    }
+  }
+  return normalizedPath;
+}
+function updatesToValueMap(updates, basePath = "", pathMappings = DEFAULT_PATH_MAPPINGS) {
+  const entries = [];
+  for (const update of updates) {
+    const rawPath = update.path.startsWith("/") ? update.path : `${basePath}/${update.path}`;
+    const normalizedPath = normalizePath(rawPath, pathMappings);
+    if (update.value !== null && typeof update.value === "object" && !Array.isArray(update.value)) {
+      const flattenedEntries = flattenObjectToValueMap(
+        update.value,
+        normalizedPath
+      );
+      entries.push(...flattenedEntries);
+    } else {
+      entries.push(valueToValueMap(normalizedPath, update.value));
+    }
+  }
+  return entries;
+}
+function flattenObjectToValueMap(obj, basePath) {
+  const entries = [];
+  for (const [key, value] of Object.entries(obj)) {
+    const fullPath = `${basePath}/${key}`;
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      const nestedEntries = flattenObjectToValueMap(value, fullPath);
+      entries.push(...nestedEntries);
+    } else {
+      entries.push(valueToValueMap(fullPath, value));
+    }
+  }
+  return entries;
+}
+function valueMapToObject(valueMaps) {
+  const result = {};
+  for (const valueMap of valueMaps) {
+    const key = valueMap.key.startsWith("/") ? valueMap.key.slice(1) : valueMap.key;
+    if (valueMap.valueString !== void 0) {
+      result[key] = valueMap.valueString;
+    } else if (valueMap.valueNumber !== void 0) {
+      result[key] = valueMap.valueNumber;
+    } else if (valueMap.valueBoolean !== void 0) {
+      result[key] = valueMap.valueBoolean;
+    } else if (valueMap.valueMap !== void 0) {
+      result[key] = valueMapToObject(valueMap.valueMap);
+    }
+  }
+  return result;
+}
+
+// src/builders/message-builder.ts
+function createSurface(surfaceId, catalogId = STANDARD_CATALOG_ID) {
+  return {
+    createSurface: {
+      surfaceId,
+      catalogId
+    }
+  };
+}
+function updateComponents(surfaceId, components) {
+  return {
+    updateComponents: {
+      surfaceId,
+      components
+    }
+  };
+}
+function updateDataModel(surfaceId, value, path, op = "replace") {
+  return {
+    updateDataModel: {
+      surfaceId,
+      ...path && { path },
+      op,
+      ...op !== "remove" && { value }
+    }
+  };
+}
+function deleteSurface(surfaceId) {
+  return {
+    deleteSurface: {
+      surfaceId
+    }
+  };
+}
+function createV09Messages(options) {
+  const { surfaceId, catalogId = STANDARD_CATALOG_ID, components, dataModel } = options;
+  const messages = [
+    createSurface(surfaceId, catalogId),
+    updateComponents(surfaceId, components)
+  ];
+  if (dataModel) {
+    messages.push(updateDataModel(surfaceId, dataModel));
+  }
+  return messages;
+}
+function beginRendering(rootId, surfaceId = "@default", styles) {
+  return {
+    beginRendering: {
+      surfaceId,
+      root: rootId,
+      ...styles && { styles }
+    }
+  };
+}
+function surfaceUpdate(components, surfaceId = "@default") {
+  return {
+    surfaceUpdate: {
+      surfaceId,
+      components
+    }
+  };
+}
+function dataModelUpdate(contents, surfaceId = "@default", path) {
+  return {
+    dataModelUpdate: {
+      surfaceId,
+      contents,
+      ...path && { path }
+    }
+  };
+}
+function dataModelInit(data, surfaceId = "@default") {
+  return dataModelUpdate(objectToValueMap(data), surfaceId);
+}
+function pathUpdate(path, value, surfaceId = "@default") {
+  return {
+    dataModelUpdate: {
+      surfaceId,
+      path,
+      contents: [valueToValueMap("", value)]
+    }
+  };
+}
+function deleteSurfaceV08(surfaceId) {
+  return {
+    deleteSurface: {
+      surfaceId
+    }
+  };
+}
+function createV08Messages(options) {
+  const { rootId, components, dataModel, surfaceId = "@default", styles } = options;
+  const messages = [
+    surfaceUpdate(components, surfaceId)
+  ];
+  if (dataModel) {
+    messages.push(dataModelInit(dataModel, surfaceId));
+  }
+  messages.push(beginRendering(rootId, surfaceId, styles));
+  return messages;
+}
+function messagesToJsonl(messages) {
+  return messages.map((msg) => JSON.stringify(msg)).join("\n");
+}
+function jsonlToMessages(jsonl) {
+  return jsonl.split("\n").filter((line) => line.trim()).map((line) => JSON.parse(line));
+}
+
+exports.DEFAULT_PATH_MAPPINGS = DEFAULT_PATH_MAPPINGS;
+exports.audioPlayer = audioPlayer;
+exports.beginRendering = beginRendering;
+exports.body = body;
+exports.button = button;
+exports.caption = caption;
+exports.card = card;
+exports.checkbox = checkbox;
+exports.choicePicker = choicePicker;
+exports.column = column;
+exports.createSurface = createSurface;
+exports.createV08Messages = createV08Messages;
+exports.createV09Messages = createV09Messages;
+exports.dataModelInit = dataModelInit;
+exports.dataModelUpdate = dataModelUpdate;
+exports.dateTimeInput = dateTimeInput;
+exports.deleteSurface = deleteSurface;
+exports.deleteSurfaceV08 = deleteSurfaceV08;
+exports.divider = divider;
+exports.flattenObjectToValueMap = flattenObjectToValueMap;
+exports.generateId = generateId;
+exports.getIdCounter = getIdCounter;
+exports.h1 = h1;
+exports.h2 = h2;
+exports.h3 = h3;
+exports.h4 = h4;
+exports.h5 = h5;
+exports.icon = icon;
+exports.image = image;
+exports.jsonlToMessages = jsonlToMessages;
+exports.list = list;
+exports.messagesToJsonl = messagesToJsonl;
+exports.modal = modal;
+exports.normalizePath = normalizePath;
+exports.objectToValueMap = objectToValueMap;
+exports.pathUpdate = pathUpdate;
+exports.resetIdCounter = resetIdCounter;
+exports.row = row;
+exports.slider = slider;
+exports.surfaceUpdate = surfaceUpdate;
+exports.tabs = tabs;
+exports.text = text;
+exports.textButton = textButton;
+exports.textField = textField;
+exports.updateComponents = updateComponents;
+exports.updateDataModel = updateDataModel;
+exports.updatesToValueMap = updatesToValueMap;
+exports.valueMapToObject = valueMapToObject;
+exports.valueToValueMap = valueToValueMap;
+exports.video = video;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map