@lynx-js/genui 0.0.1-rc.0

package/a2ui/dist/catalog/TextField/catalog.json

@@ -0,0 +1,147 @@
+{
+  "TextField": {
+    "properties": {
+      "label": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "path"
+            ],
+            "additionalProperties": false
+          }
+        ],
+        "description": "The text label for the input field."
+      },
+      "value": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "path"
+            ],
+            "additionalProperties": false
+          }
+        ],
+        "description": "The value of the text field."
+      },
+      "variant": {
+        "type": "string",
+        "enum": [
+          "number",
+          "longText",
+          "shortText",
+          "obscured"
+        ],
+        "description": "The type of input field to display."
+      },
+      "validationRegexp": {
+        "type": "string",
+        "description": "A regular expression used for client-side validation of the input."
+      },
+      "checks": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "condition": {
+              "oneOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "path": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "path"
+                  ],
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "call": {
+                      "type": "string"
+                    },
+                    "args": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "oneOf": [
+                          {
+                            "type": "string"
+                          },
+                          {
+                            "type": "number"
+                          },
+                          {
+                            "type": "boolean"
+                          },
+                          {
+                            "type": "object",
+                            "properties": {
+                              "path": {
+                                "type": "string"
+                              }
+                            },
+                            "required": [
+                              "path"
+                            ],
+                            "additionalProperties": false
+                          }
+                        ]
+                      }
+                    },
+                    "returnType": {
+                      "type": "string",
+                      "enum": [
+                        "boolean"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "call"
+                  ],
+                  "additionalProperties": false
+                }
+              ],
+              "description": "The condition that indicates whether the check passes."
+            },
+            "message": {
+              "type": "string",
+              "description": "The error message to display if the check fails."
+            }
+          },
+          "required": [
+            "condition",
+            "message"
+          ],
+          "additionalProperties": false
+        },
+        "description": "A list of checks to perform."
+      }
+    },
+    "required": [
+      "label"
+    ]
+  }
+}

package/a2ui/dist/catalog/TextField/index.d.ts

@@ -0,0 +1,35 @@
+import type { GenericComponentProps } from '../../store/types.js';
+import '../../../styles/catalog/TextField.css';
+/**
+ * @a2uiCatalog TextField
+ */
+export interface TextFieldProps extends GenericComponentProps {
+    /** The text label for the input field. */
+    label: string | {
+        path: string;
+    };
+    /** The value of the text field. */
+    value?: string | {
+        path: string;
+    };
+    /** The type of input field to display. */
+    variant?: 'longText' | 'number' | 'shortText' | 'obscured';
+    /** A regular expression used for client-side validation of the input. */
+    validationRegexp?: string;
+    /** A list of checks to perform. */
+    checks?: Array<{
+        /** The condition that indicates whether the check passes. */
+        condition: boolean | {
+            path: string;
+        } | {
+            call: string;
+            args?: Record<string, string | number | boolean | {
+                path: string;
+            }>;
+            returnType?: 'boolean';
+        };
+        /** The error message to display if the check fails. */
+        message: string;
+    }>;
+}
+export declare function TextField(props: TextFieldProps): import('@lynx-js/react').ReactNode;

package/a2ui/dist/catalog/TextField/index.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@lynx-js/react/jsx-runtime";
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { Input, TextArea } from '@lynx-js/lynx-ui';
+import { useEffect, useState } from '@lynx-js/react';
+import { getTextFieldInputType, isTextFieldValueValid, normalizeTextFieldValue, normalizeTextFieldVariant, } from './utils.js';
+import '../../../styles/catalog/TextField.css';
+export function TextField(props) {
+    const { id, label, setValue, validationRegexp } = props;
+    const textFieldType = props['textFieldType'];
+    const variant = normalizeTextFieldVariant(props.variant, textFieldType);
+    const resolvedValue = normalizeTextFieldValue(props.value);
+    const labelText = normalizeTextFieldValue(label);
+    const [draftValue, setDraftValue] = useState(resolvedValue);
+    const [touched, setTouched] = useState(false);
+    useEffect(() => {
+        setDraftValue(resolvedValue);
+        return undefined;
+    }, [resolvedValue]);
+    const handleInput = (nextValue) => {
+        setTouched(true);
+        setDraftValue(nextValue);
+        setValue?.('value', nextValue);
+    };
+    const handleBlur = () => {
+        setTouched(true);
+    };
+    const invalid = !isTextFieldValueValid(draftValue, validationRegexp);
+    const showInvalid = touched && invalid;
+    const rootClassName = showInvalid
+        ? `textfield textfield-${variant} textfield-invalid`
+        : `textfield textfield-${variant}`;
+    const controlClassName = variant === 'longText'
+        ? 'textfield-control textfield-textarea'
+        : 'textfield-control';
+    const controlId = id ? `${id}-control` : undefined;
+    const controlIdProps = controlId ? { id: controlId } : {};
+    return (_jsxs("view", { className: rootClassName, children: [_jsx("text", { className: 'textfield-label', children: labelText }), variant === 'longText'
+                ? (_jsx(TextArea, { ...controlIdProps, className: controlClassName, value: draftValue, maxLines: 6, confirmType: 'done', onInput: handleInput, onBlur: handleBlur }))
+                : (_jsx(Input, { ...controlIdProps, className: controlClassName, value: draftValue, type: getTextFieldInputType(variant), confirmType: 'done', onInput: handleInput, onBlur: handleBlur })), showInvalid && _jsx("text", { className: 'textfield-error', children: "Invalid value" })] }, id));
+}
+//# sourceMappingURL=index.js.map

package/a2ui/dist/catalog/TextField/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/catalog/TextField/index.tsx"],"names":[],"mappings":"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"}

package/a2ui/dist/catalog/TextField/utils.d.ts

@@ -0,0 +1,7 @@
+export type TextFieldVariant = 'longText' | 'number' | 'obscured' | 'shortText';
+export declare const TEXT_FIELD_VARIANTS: readonly TextFieldVariant[];
+export type TextFieldInputType = 'number' | 'password' | 'text';
+export declare function normalizeTextFieldVariant(variant: unknown, textFieldType?: unknown): TextFieldVariant;
+export declare function getTextFieldInputType(variant: TextFieldVariant): TextFieldInputType;
+export declare function normalizeTextFieldValue(value: unknown): string;
+export declare function isTextFieldValueValid(value: string, validationRegexp: unknown): boolean;

package/a2ui/dist/catalog/TextField/utils.js

@@ -0,0 +1,51 @@
+export const TEXT_FIELD_VARIANTS = [
+    'longText',
+    'number',
+    'shortText',
+    'obscured',
+];
+export function normalizeTextFieldVariant(variant, textFieldType) {
+    const preferred = typeof variant === 'string' ? variant : undefined;
+    const fallback = typeof textFieldType === 'string'
+        ? textFieldType
+        : undefined;
+    if (isTextFieldVariant(preferred))
+        return preferred;
+    if (isTextFieldVariant(fallback))
+        return fallback;
+    return 'shortText';
+}
+export function getTextFieldInputType(variant) {
+    if (variant === 'number')
+        return 'number';
+    if (variant === 'obscured')
+        return 'password';
+    return 'text';
+}
+export function normalizeTextFieldValue(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number'
+        || typeof value === 'boolean'
+        || typeof value === 'bigint') {
+        return String(value);
+    }
+    return '';
+}
+export function isTextFieldValueValid(value, validationRegexp) {
+    if (typeof validationRegexp !== 'string' || validationRegexp.length === 0) {
+        return true;
+    }
+    try {
+        return new RegExp(validationRegexp).test(value);
+    }
+    catch {
+        return true;
+    }
+}
+function isTextFieldVariant(value) {
+    return TEXT_FIELD_VARIANTS.includes(value);
+}
+//# sourceMappingURL=utils.js.map

package/a2ui/dist/catalog/TextField/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/catalog/TextField/utils.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,mBAAmB,GAAgC;IAC9D,UAAU;IACV,QAAQ;IACR,WAAW;IACX,UAAU;CACX,CAAC;AAIF,MAAM,UAAU,yBAAyB,CACvC,OAAgB,EAChB,aAAuB;IAEvB,MAAM,SAAS,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,MAAM,QAAQ,GAAG,OAAO,aAAa,KAAK,QAAQ;QAChD,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,SAAS,CAAC;IAEd,IAAI,kBAAkB,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,IAAI,kBAAkB,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAClD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,OAAyB;IAEzB,IAAI,OAAO,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC1C,IAAI,OAAO,KAAK,UAAU;QAAE,OAAO,UAAU,CAAC;IAC9C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IACE,OAAO,KAAK,KAAK,QAAQ;WACtB,OAAO,KAAK,KAAK,SAAS;WAC1B,OAAO,KAAK,KAAK,QAAQ,EAC5B,CAAC;QACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,gBAAyB;IAEzB,IAAI,OAAO,gBAAgB,KAAK,QAAQ,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1E,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CACzB,KAAyB;IAEzB,OAAO,mBAAmB,CAAC,QAAQ,CAAC,KAAyB,CAAC,CAAC;AACjE,CAAC"}

package/a2ui/dist/catalog/defineCatalog.d.ts

@@ -0,0 +1,119 @@
+import type { ComponentType } from '@lynx-js/react';
+import type { FunctionDefinition, FunctionImpl } from '../store/FunctionRegistry.js';
+import type { GenericComponentProps } from '../store/types.js';
+/**
+ * JSON Schema fragment describing a component's props. Produced at build time
+ * by `@lynx-js/genui/a2ui-catalog-extractor` from the component's TypeScript
+ * interface marked with `@a2uiCatalog <Name>`. Optional at runtime — entries
+ * that ship without a schema serialize to just `{ name }`.
+ */
+export type CatalogSchema = Record<string, unknown>;
+/**
+ * The shape produced by the extractor as `dist/catalog/<Name>/catalog.json`.
+ * The single top-level key is the component's protocol name; the value is
+ * its schema. Importing the JSON gives you both, in one declaration.
+ */
+export type CatalogManifest = Record<string, CatalogSchema>;
+/**
+ * Loose component type — entries receive runtime-shaped props from the
+ * protocol stream, so we don't enforce per-component prop typing here.
+ */
+export type CatalogComponent = ComponentType<GenericComponentProps>;
+/**
+ * A function-definition manifest as emitted by the extractor under
+ * `dist/catalog/functions/<name>.json`.
+ */
+/**
+ * The structured function definition that flows from the extractor (or the
+ * upstream basic-catalog manifests) into the catalog and out to the agent
+ * during the handshake. Aliased onto the store's `FunctionDefinition` so
+ * `functionRegistry.register({ definition })` accepts catalog entries
+ * directly without re-shaping.
+ */
+export type CatalogFunctionDefinition = FunctionDefinition;
+export type FunctionManifest = Record<string, CatalogFunctionDefinition>;
+/**
+ * A function entry — pair an impl with its name, plus an optional manifest
+ * so the handshake can announce the schema to the agent.
+ */
+export interface CatalogFunctionEntry {
+    kind: 'function';
+    name: string;
+    impl: FunctionImpl;
+    definition?: CatalogFunctionDefinition;
+}
+/**
+ * Build a function entry for `defineCatalog`. Either pair the impl with the
+ * extracted manifest, or pass just the impl (the registry still routes
+ * calls; the agent just won't see the parameter schema).
+ *
+ * @example
+ * const requiredEntry = defineFunction(required, requiredManifest);
+ * const catalog = defineCatalog([Text, Button, requiredEntry]);
+ */
+export declare function defineFunction(impl: FunctionImpl, manifest?: FunctionManifest): CatalogFunctionEntry;
+/**
+ * What the developer passes into `defineCatalog`. Components and function
+ * entries can be intermixed.
+ */
+export type CatalogInput = CatalogComponent | readonly [CatalogComponent, CatalogManifest] | ResolvedCatalogEntry | CatalogFunctionEntry;
+/**
+ * A resolved catalog entry. Internal representation; consumers don't usually
+ * construct these directly — they pass `CatalogInput`s to `defineCatalog`.
+ */
+export interface ResolvedCatalogEntry {
+    name: string;
+    component: CatalogComponent;
+    schema?: CatalogSchema;
+}
+export interface Catalog {
+    readonly components: readonly ResolvedCatalogEntry[];
+    readonly functions: readonly CatalogFunctionEntry[];
+}
+/** The serialized payload sent to the agent during channel handshake. */
+export interface SerializedCatalog {
+    version: '0.9';
+    components: Array<{
+        name: string;
+        schema?: CatalogSchema;
+    }>;
+    functions?: CatalogFunctionDefinition[];
+}
+/**
+ * Build a catalog from a list of components, `[component, manifest]` pairs,
+ * and/or function entries. Duplicate names within the same kind are rejected.
+ * Function entries register their impls into `functionRegistry` immediately,
+ * so any `executeFunctionCall` after `defineCatalog` can route to them.
+ *
+ * @example
+ * import { Text, Button } from '@lynx-js/genui/a2ui';
+ * import { defineCatalog, defineFunction } from '@lynx-js/genui/a2ui';
+ * import { required } from '@lynx-js/genui/a2ui/functions';
+ * import textManifest from '@lynx-js/genui/a2ui/catalog/Text/catalog.json'
+ *   with { type: 'json' };
+ *
+ * const catalog = defineCatalog([
+ *   [Text, textManifest],
+ *   Button,
+ *   defineFunction(required),
+ * ]);
+ */
+export declare function defineCatalog(inputs: readonly CatalogInput[]): Catalog;
+/**
+ * Merge multiple catalogs. Last write wins on duplicate names — useful when
+ * a page-level catalog overrides a brand-level one which overrides built-ins.
+ */
+export declare function mergeCatalogs(...catalogs: Catalog[]): Catalog;
+/**
+ * Build a name → component lookup map from a catalog. The renderer uses
+ * this to resolve `{ component: 'Text', ... }` from the protocol stream.
+ */
+export declare function resolveCatalog(catalog: Catalog): ReadonlyMap<string, CatalogComponent>;
+/**
+ * Produce the JSON manifest the client should announce to the agent during
+ * channel handshake. Component entries without an attached schema serialize
+ * to `{ name }` only — useful for letting the agent at least know what's
+ * renderable. Function entries serialize with their parameter schema when
+ * available.
+ */
+export declare function serializeCatalog(catalog: Catalog): SerializedCatalog;

package/a2ui/dist/catalog/defineCatalog.js

@@ -0,0 +1,196 @@
+import { functionRegistry } from '../store/FunctionRegistry.js';
+/**
+ * Build a function entry for `defineCatalog`. Either pair the impl with the
+ * extracted manifest, or pass just the impl (the registry still routes
+ * calls; the agent just won't see the parameter schema).
+ *
+ * @example
+ * const requiredEntry = defineFunction(required, requiredManifest);
+ * const catalog = defineCatalog([Text, Button, requiredEntry]);
+ */
+export function defineFunction(impl, manifest) {
+    if (manifest) {
+        const keys = Object.keys(manifest);
+        if (keys.length === 0) {
+            throw new Error('[a2ui] Empty manifest passed to defineFunction; expected '
+                + '`{ <functionName>: definition }`.');
+        }
+        const name = keys[0];
+        const definition = manifest[name];
+        return {
+            kind: 'function',
+            name,
+            impl,
+            definition,
+        };
+    }
+    const name = impl.displayName
+        ?? impl.name;
+    if (!name) {
+        throw new Error('[a2ui] Cannot add a function to the catalog: no name available. '
+            + 'Pair it with its manifest as `defineFunction(impl, manifest)`, '
+            + 'or set `impl.displayName = "..."`.');
+    }
+    return { kind: 'function', name, impl };
+}
+function isFunctionEntry(input) {
+    return typeof input === 'object'
+        && input !== null
+        && !Array.isArray(input)
+        && input.kind === 'function';
+}
+function isResolvedEntry(input) {
+    return typeof input === 'object'
+        && input !== null
+        && !Array.isArray(input)
+        && 'component' in input
+        && 'name' in input
+        && !isFunctionEntry(input);
+}
+function isTuple(input) {
+    return Array.isArray(input);
+}
+function deriveBareName(component) {
+    const name = component.displayName
+        ?? component.name;
+    if (!name) {
+        throw new Error('[a2ui] Cannot add a component to the catalog: no displayName or '
+            + 'function name. This typically happens when the bundler '
+            + 'minifies function names. Set `Foo.displayName = "Foo"` after '
+            + 'the component declaration (the string literal survives '
+            + 'minification), or pair it with its `catalog.json` manifest as '
+            + '`[Foo, fooManifest]`.');
+    }
+    return name;
+}
+function resolveComponentInput(input) {
+    if (isResolvedEntry(input))
+        return input;
+    if (isTuple(input)) {
+        const [component, manifest] = input;
+        const keys = Object.keys(manifest);
+        if (keys.length === 0) {
+            throw new Error('[a2ui] Empty manifest passed to defineCatalog; expected '
+                + '`{ <ComponentName>: schema }`.');
+        }
+        const name = keys[0];
+        const entry = { name, component: component };
+        const schema = manifest[name];
+        if (schema !== undefined)
+            entry.schema = schema;
+        return entry;
+    }
+    return {
+        name: deriveBareName(input),
+        component: input,
+    };
+}
+/**
+ * Build a catalog from a list of components, `[component, manifest]` pairs,
+ * and/or function entries. Duplicate names within the same kind are rejected.
+ * Function entries register their impls into `functionRegistry` immediately,
+ * so any `executeFunctionCall` after `defineCatalog` can route to them.
+ *
+ * @example
+ * import { Text, Button } from '@lynx-js/genui/a2ui';
+ * import { defineCatalog, defineFunction } from '@lynx-js/genui/a2ui';
+ * import { required } from '@lynx-js/genui/a2ui/functions';
+ * import textManifest from '@lynx-js/genui/a2ui/catalog/Text/catalog.json'
+ *   with { type: 'json' };
+ *
+ * const catalog = defineCatalog([
+ *   [Text, textManifest],
+ *   Button,
+ *   defineFunction(required),
+ * ]);
+ */
+export function defineCatalog(inputs) {
+    const components = [];
+    const functions = [];
+    const seenComponents = new Set();
+    const seenFunctions = new Set();
+    for (const input of inputs) {
+        if (isFunctionEntry(input)) {
+            if (seenFunctions.has(input.name)) {
+                throw new Error(`[a2ui] Duplicate function name in catalog: "${input.name}". `
+                    + `Use mergeCatalogs() if you intend to override.`);
+            }
+            seenFunctions.add(input.name);
+            functions.push(input);
+            functionRegistry.register({
+                name: input.name,
+                impl: input.impl,
+                ...(input.definition ? { definition: input.definition } : {}),
+            });
+            continue;
+        }
+        const entry = resolveComponentInput(input);
+        if (seenComponents.has(entry.name)) {
+            throw new Error(`[a2ui] Duplicate component name in catalog: "${entry.name}". `
+                + `Use mergeCatalogs() if you intend to override.`);
+        }
+        seenComponents.add(entry.name);
+        components.push(entry);
+    }
+    return { components, functions };
+}
+/**
+ * Merge multiple catalogs. Last write wins on duplicate names — useful when
+ * a page-level catalog overrides a brand-level one which overrides built-ins.
+ */
+export function mergeCatalogs(...catalogs) {
+    const componentMap = new Map();
+    const functionMap = new Map();
+    for (const cat of catalogs) {
+        for (const entry of cat.components)
+            componentMap.set(entry.name, entry);
+        for (const fn of cat.functions)
+            functionMap.set(fn.name, fn);
+    }
+    // Re-register so the registry tracks the merged set.
+    for (const fn of functionMap.values()) {
+        functionRegistry.register({
+            name: fn.name,
+            impl: fn.impl,
+            ...(fn.definition ? { definition: fn.definition } : {}),
+        });
+    }
+    return {
+        components: Array.from(componentMap.values()),
+        functions: Array.from(functionMap.values()),
+    };
+}
+/**
+ * Build a name → component lookup map from a catalog. The renderer uses
+ * this to resolve `{ component: 'Text', ... }` from the protocol stream.
+ */
+export function resolveCatalog(catalog) {
+    const map = new Map();
+    for (const entry of catalog.components)
+        map.set(entry.name, entry.component);
+    return map;
+}
+/**
+ * Produce the JSON manifest the client should announce to the agent during
+ * channel handshake. Component entries without an attached schema serialize
+ * to `{ name }` only — useful for letting the agent at least know what's
+ * renderable. Function entries serialize with their parameter schema when
+ * available.
+ */
+export function serializeCatalog(catalog) {
+    const components = [];
+    for (const entry of catalog.components) {
+        const out = { name: entry.name };
+        if (entry.schema !== undefined)
+            out.schema = entry.schema;
+        components.push(out);
+    }
+    const serialized = { version: '0.9', components };
+    const functions = catalog.functions
+        .filter(fn => fn.definition !== undefined)
+        .map(fn => fn.definition);
+    if (functions.length > 0)
+        serialized.functions = functions;
+    return serialized;
+}
+//# sourceMappingURL=defineCatalog.js.map

package/a2ui/dist/catalog/defineCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineCatalog.js","sourceRoot":"","sources":["../../src/catalog/defineCatalog.ts"],"names":[],"mappings":"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"}

package/a2ui/dist/catalog/index.d.ts

@@ -0,0 +1,20 @@
+export { defineCatalog, defineFunction, mergeCatalogs, resolveCatalog, serializeCatalog, } from './defineCatalog.js';
+export type { Catalog, CatalogComponent, CatalogFunctionDefinition, CatalogFunctionEntry, CatalogInput, CatalogManifest, CatalogSchema, FunctionManifest, ResolvedCatalogEntry, SerializedCatalog, } from './defineCatalog.js';
+export { Button } from './Button/index.js';
+export { Card } from './Card/index.js';
+export { CheckBox } from './CheckBox/index.js';
+export { LineChart } from './LineChart/index.js';
+export { PieChart } from './PieChart/index.js';
+export { Column } from './Column/index.js';
+export { Divider } from './Divider/index.js';
+export { Icon } from './Icon/index.js';
+export { Image } from './Image/index.js';
+export { List } from './List/index.js';
+export { Modal } from './Modal/index.js';
+export { RadioGroup } from './RadioGroup/index.js';
+export { Row } from './Row/index.js';
+export { Slider } from './Slider/index.js';
+export { Tabs } from './Tabs/index.js';
+export { Text } from './Text/index.js';
+export { TextField } from './TextField/index.js';
+export { DEFAULT_CHART_COLORS, escapeXml, formatValue } from './utils/chart.js';