@a2ui-sdk/utils 0.2.1 → 0.3.0

package/README.md

@@ -43,12 +43,17 @@ import {
 import {
   // Data binding utilities
   resolveValue,
+  resolveActionContext,
   resolveStringValue,
   resolveNumberValue,
   resolveBooleanValue,
   isPathBinding,
 
   // Path utilities
+  normalizePath,
+  isAbsolutePath,
+  joinPaths,
+  resolvePath,
   parsePath,
   joinPath,
   getValueAtPath,
@@ -67,6 +72,36 @@ const { interpolate, hasInterpolation } = v0_9
 
 ## API
 
+### Scope and Path Resolution (v0.8+)
+
+Work with scoped data paths:
+
+```tsx
+import {
+  normalizePath,
+  isAbsolutePath,
+  joinPaths,
+  resolvePath,
+} from '@a2ui-sdk/utils/0.8'
+
+// Normalize path format
+normalizePath('user/name') // '/user/name'
+normalizePath('/items/') // '/items'
+
+// Check if path is absolute
+isAbsolutePath('/user/name') // true
+isAbsolutePath('name') // false
+
+// Join base path with relative path
+joinPaths('/items/0', 'name') // '/items/0/name'
+joinPaths('/items', '../users') // '/users'
+
+// Resolve path with scope
+resolvePath('/user/name', '/items/0') // '/user/name' (absolute, ignores basePath)
+resolvePath('name', '/items/0') // '/items/0/name' (relative, uses basePath)
+resolvePath('name', null) // '/name' (treats relative as absolute when no basePath)
+```
+
 ### String Interpolation (v0.9)
 
 Process strings with embedded expressions:
@@ -102,6 +137,18 @@ resolveValue({ path: '/user/name' }, dataModel) // 'Alice'
 resolveValue('static value', dataModel) // 'static value'
 ```
 
+`resolveValue` also supports scoped path resolution:
+
+```tsx
+import { resolveValue } from '@a2ui-sdk/utils/0.9'
+
+const dataModel = { items: [{ name: 'Item 1' }, { name: 'Item 2' }] }
+
+// Resolve with basePath for scoped data access
+resolveValue({ path: 'name' }, dataModel, '/items/0') // 'Item 1'
+resolveValue({ path: '/items/1/name' }, dataModel, '/items/0') // 'Item 2' (absolute path ignores basePath)
+```
+
 ### Path Utilities
 
 Work with JSON Pointer paths (RFC 6901):

package/dist/0.8/dataBinding.d.ts

@@ -8,20 +8,24 @@ import type { ValueSource, DataModel, DataEntry, DataModelValue } from '@a2ui-sd
  *
  * @param source - The value source (literal or path reference)
  * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for resolving relative paths (null for root scope)
  * @param defaultValue - Default value if source is undefined or path not found
  * @returns The resolved value
  *
  * @example
  * // Literal values
- * resolveValue({ literalString: "Hello" }, {}); // "Hello"
- * resolveValue({ literalNumber: 42 }, {});      // 42
+ * resolveValue({ literalString: "Hello" }, {}, null); // "Hello"
+ * resolveValue({ literalNumber: 42 }, {}, null);      // 42
  *
- * // Path references
+ * // Path references (absolute paths)
  * const model = { user: { name: "John" } };
- * resolveValue({ path: "/user/name" }, model);  // "John"
- * resolveValue({ path: "/user/age" }, model, 0); // 0 (default)
+ * resolveValue({ path: "/user/name" }, model, null);  // "John"
+ * resolveValue({ path: "/user/age" }, model, null, 0); // 0 (default)
+ *
+ * // Path references (relative paths with scope)
+ * resolveValue({ path: "name" }, model, "/user");  // "John" (resolves to "/user/name")
  */
-export declare function resolveValue<T = unknown>(source: ValueSource | undefined, dataModel: DataModel, defaultValue?: T): T;
+export declare function resolveValue<T = unknown>(source: ValueSource | undefined, dataModel: DataModel, basePath?: string | null, defaultValue?: T): T;
 /**
  * Converts a DataEntry array to a plain object.
  * This is used for processing dataModelUpdate message contents.
@@ -47,9 +51,10 @@ export declare function contentsToObject(contents: DataEntry[]): Record<string,
  *
  * @param context - Array of action context items
  * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for resolving relative paths (null for root scope)
  * @returns A plain object with resolved context values
  */
 export declare function resolveActionContext(context: Array<{
     key: string;
     value: ValueSource;
-}> | undefined, dataModel: DataModel): Record<string, unknown>;
+}> | undefined, dataModel: DataModel, basePath?: string | null): Record<string, unknown>;

package/dist/0.8/dataBinding.js

@@ -2,26 +2,30 @@
  * Data binding utility functions for A2UI.
  * Handles resolving value sources and converting data entries.
  */
-import { getValueByPath } from './pathUtils.js';
+import { getValueByPath, resolvePath } from './pathUtils.js';
 /**
  * Resolves a ValueSource to its actual value.
  *
  * @param source - The value source (literal or path reference)
  * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for resolving relative paths (null for root scope)
  * @param defaultValue - Default value if source is undefined or path not found
  * @returns The resolved value
  *
  * @example
  * // Literal values
- * resolveValue({ literalString: "Hello" }, {}); // "Hello"
- * resolveValue({ literalNumber: 42 }, {});      // 42
+ * resolveValue({ literalString: "Hello" }, {}, null); // "Hello"
+ * resolveValue({ literalNumber: 42 }, {}, null);      // 42
  *
- * // Path references
+ * // Path references (absolute paths)
  * const model = { user: { name: "John" } };
- * resolveValue({ path: "/user/name" }, model);  // "John"
- * resolveValue({ path: "/user/age" }, model, 0); // 0 (default)
+ * resolveValue({ path: "/user/name" }, model, null);  // "John"
+ * resolveValue({ path: "/user/age" }, model, null, 0); // 0 (default)
+ *
+ * // Path references (relative paths with scope)
+ * resolveValue({ path: "name" }, model, "/user");  // "John" (resolves to "/user/name")
  */
-export function resolveValue(source, dataModel, defaultValue) {
+export function resolveValue(source, dataModel, basePath = null, defaultValue) {
     if (source === undefined || source === null) {
         return defaultValue;
     }
@@ -38,7 +42,9 @@ export function resolveValue(source, dataModel, defaultValue) {
         return source.literalArray;
     }
     if ('path' in source) {
-        const value = getValueByPath(dataModel, source.path);
+        // Resolve path against base path (scope)
+        const resolvedPath = resolvePath(source.path, basePath);
+        const value = getValueByPath(dataModel, resolvedPath);
         if (value === undefined) {
             return defaultValue;
         }
@@ -104,15 +110,16 @@ function normalizeKey(key) {
  *
  * @param context - Array of action context items
  * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for resolving relative paths (null for root scope)
  * @returns A plain object with resolved context values
  */
-export function resolveActionContext(context, dataModel) {
+export function resolveActionContext(context, dataModel, basePath = null) {
     if (!context) {
         return {};
     }
     const result = {};
     for (const item of context) {
-        result[item.key] = resolveValue(item.value, dataModel);
+        result[item.key] = resolveValue(item.value, dataModel, basePath);
     }
     return result;
 }

package/dist/0.8/pathUtils.d.ts

@@ -40,3 +40,63 @@ export declare function setValueByPath(dataModel: DataModel, path: string, value
  * @returns A new data model with the data merged
  */
 export declare function mergeAtPath(dataModel: DataModel, path: string, data: Record<string, unknown>): DataModel;
+/**
+ * Normalizes a path to ensure it starts with "/" and has no trailing "/".
+ *
+ * @param path - The path to normalize
+ * @returns The normalized path
+ *
+ * @example
+ * normalizePath("user/name");   // "/user/name"
+ * normalizePath("/items/");     // "/items"
+ * normalizePath("/data");       // "/data"
+ * normalizePath("");            // "/"
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * Checks if a path is absolute (starts with "/").
+ *
+ * @param path - The path to check
+ * @returns True if the path is absolute, false otherwise
+ *
+ * @example
+ * isAbsolutePath("/user/name");  // true
+ * isAbsolutePath("name");        // false
+ * isAbsolutePath("");            // false
+ */
+export declare function isAbsolutePath(path: string): boolean;
+/**
+ * Joins two paths together.
+ *
+ * @param basePath - The base path (should be absolute)
+ * @param relativePath - The relative path to append
+ * @returns The combined path
+ *
+ * @example
+ * joinPaths("/items/0", "name");      // "/items/0/name"
+ * joinPaths("/user", "profile/age");  // "/user/profile/age"
+ * joinPaths("/data", "");             // "/data"
+ */
+export declare function joinPaths(basePath: string, relativePath: string): string;
+/**
+ * Resolves a path against a base path (scope).
+ * - Absolute paths (starting with "/") are returned normalized, ignoring the base path
+ * - Relative paths are resolved against the base path if provided
+ * - If base path is null, relative paths are treated as absolute
+ *
+ * @param path - The path to resolve (absolute or relative)
+ * @param basePath - The base path for resolving relative paths (null for root scope)
+ * @returns The resolved absolute path
+ *
+ * @example
+ * // Absolute paths ignore base path
+ * resolvePath("/user/name", "/items/0");  // "/user/name"
+ *
+ * // Relative paths resolve against base path
+ * resolvePath("name", "/items/0");        // "/items/0/name"
+ * resolvePath("profile/age", "/user");    // "/user/profile/age"
+ *
+ * // Relative paths with null base path (root scope)
+ * resolvePath("name", null);              // "/name"
+ */
+export declare function resolvePath(path: string, basePath: string | null): string;

package/dist/0.8/pathUtils.js

@@ -109,3 +109,98 @@ export function mergeAtPath(dataModel, path, data) {
     const merged = { ...currentObj, ...data };
     return setValueByPath(dataModel, path, merged);
 }
+/**
+ * Normalizes a path to ensure it starts with "/" and has no trailing "/".
+ *
+ * @param path - The path to normalize
+ * @returns The normalized path
+ *
+ * @example
+ * normalizePath("user/name");   // "/user/name"
+ * normalizePath("/items/");     // "/items"
+ * normalizePath("/data");       // "/data"
+ * normalizePath("");            // "/"
+ */
+export function normalizePath(path) {
+    if (!path) {
+        return '/';
+    }
+    // Ensure leading slash
+    let normalized = path.startsWith('/') ? path : `/${path}`;
+    // Remove trailing slash (unless it's the root path)
+    if (normalized.length > 1 && normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+/**
+ * Checks if a path is absolute (starts with "/").
+ *
+ * @param path - The path to check
+ * @returns True if the path is absolute, false otherwise
+ *
+ * @example
+ * isAbsolutePath("/user/name");  // true
+ * isAbsolutePath("name");        // false
+ * isAbsolutePath("");            // false
+ */
+export function isAbsolutePath(path) {
+    return path.startsWith('/');
+}
+/**
+ * Joins two paths together.
+ *
+ * @param basePath - The base path (should be absolute)
+ * @param relativePath - The relative path to append
+ * @returns The combined path
+ *
+ * @example
+ * joinPaths("/items/0", "name");      // "/items/0/name"
+ * joinPaths("/user", "profile/age");  // "/user/profile/age"
+ * joinPaths("/data", "");             // "/data"
+ */
+export function joinPaths(basePath, relativePath) {
+    if (!relativePath) {
+        return normalizePath(basePath);
+    }
+    // Remove leading slash from relative path if present
+    const cleanRelative = relativePath.startsWith('/')
+        ? relativePath.slice(1)
+        : relativePath;
+    // Combine paths
+    const combined = `${normalizePath(basePath)}/${cleanRelative}`;
+    return normalizePath(combined);
+}
+/**
+ * Resolves a path against a base path (scope).
+ * - Absolute paths (starting with "/") are returned normalized, ignoring the base path
+ * - Relative paths are resolved against the base path if provided
+ * - If base path is null, relative paths are treated as absolute
+ *
+ * @param path - The path to resolve (absolute or relative)
+ * @param basePath - The base path for resolving relative paths (null for root scope)
+ * @returns The resolved absolute path
+ *
+ * @example
+ * // Absolute paths ignore base path
+ * resolvePath("/user/name", "/items/0");  // "/user/name"
+ *
+ * // Relative paths resolve against base path
+ * resolvePath("name", "/items/0");        // "/items/0/name"
+ * resolvePath("profile/age", "/user");    // "/user/profile/age"
+ *
+ * // Relative paths with null base path (root scope)
+ * resolvePath("name", null);              // "/name"
+ */
+export function resolvePath(path, basePath) {
+    // Absolute paths are used as-is (ignore base path)
+    if (isAbsolutePath(path)) {
+        return normalizePath(path);
+    }
+    // Root scope (null or "/" base path) - treat relative path as absolute
+    if (basePath === null || basePath === '/') {
+        return normalizePath(path);
+    }
+    // Relative path with scope - join with base path
+    return joinPaths(basePath, path);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2ui-sdk/utils",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A2UI utilities",
   "homepage": "https://a2ui-sdk.js.org/",
   "repository": {
@@ -43,6 +43,6 @@
     "vitest": "^4.0.16"
   },
   "dependencies": {
-    "@a2ui-sdk/types": "0.2.1"
+    "@a2ui-sdk/types": "0.3.0"
   }
 }