@player-tools/fluent 0.12.1--canary.241.6077

package/src/core/base-builder/resolution/steps/mixed-arrays.ts

@@ -0,0 +1,95 @@
+import type { BaseBuildContext } from "../../types";
+import type { ValueStorage } from "../../storage/value-storage";
+import { isAssetWrapperValue } from "../../guards";
+import { resolveAndWrapAsset } from "../value-resolver";
+
+/**
+ * Step 5: Resolves mixed arrays
+ *
+ * Processes arrays containing both builders and static values.
+ * Builders are resolved with proper context, static values pass through.
+ *
+ * @param storage - The value storage
+ * @param result - The result object being built
+ * @param nestedParentContext - Context for nested builders
+ */
+export function resolveMixedArrays<T, C extends BaseBuildContext>(
+  storage: ValueStorage<T>,
+  result: Record<string, unknown>,
+  nestedParentContext: C | undefined,
+): void {
+  const mixedArrays = storage.getMixedArrays();
+
+  mixedArrays.forEach((metadata, key) => {
+    const { array, builderIndices, objectIndices } = metadata;
+
+    // Check if this is an AssetWrapper array
+    const currentValue = result[key];
+    if (isAssetWrapperValue(currentValue)) {
+      resolveMixedArrayAsAssetWrapper(
+        result,
+        key,
+        currentValue,
+        nestedParentContext,
+      );
+    } else {
+      resolveMixedArrayNormal(
+        result,
+        key,
+        array,
+        builderIndices,
+        objectIndices,
+        nestedParentContext,
+      );
+    }
+  });
+}
+
+/**
+ * Helper: Resolves mixed array that is wrapped in AssetWrapper
+ */
+function resolveMixedArrayAsAssetWrapper<C extends BaseBuildContext>(
+  result: Record<string, unknown>,
+  key: string,
+  wrapperValue: { asset: unknown },
+  nestedParentContext: C | undefined,
+): void {
+  const unwrappedArray = wrapperValue.asset;
+
+  if (Array.isArray(unwrappedArray)) {
+    // Filter out null/undefined values before processing
+    result[key] = unwrappedArray
+      .filter((item) => item !== null && item !== undefined)
+      .map((item, index) => {
+        const slotName = `${key}-${index}`;
+        return resolveAndWrapAsset(item, {
+          context: nestedParentContext,
+          slotName,
+        });
+      });
+  }
+}
+
+/**
+ * Helper: Resolves mixed array normally (not wrapped)
+ * Uses resolveAndWrapAsset to properly wrap Asset builders in { asset: ... } format
+ */
+function resolveMixedArrayNormal<C extends BaseBuildContext>(
+  result: Record<string, unknown>,
+  key: string,
+  array: readonly unknown[],
+  builderIndices: ReadonlySet<number>,
+  objectIndices: ReadonlySet<number>,
+  nestedParentContext: C | undefined,
+): void {
+  // Filter out null/undefined values and resolve each item with proper wrapping
+  result[key] = array
+    .filter((item) => item !== null && item !== undefined)
+    .map((item, index) => {
+      const slotName = `${key}-${index}`;
+      return resolveAndWrapAsset(item, {
+        context: nestedParentContext,
+        slotName,
+      });
+    });
+}

package/src/core/base-builder/resolution/steps/nested-asset-wrappers.ts

@@ -0,0 +1,124 @@
+import type { BaseBuildContext } from "../../types";
+import { resolveAndWrapAsset, resolveValue } from "../value-resolver";
+import {
+  isAsset,
+  isAssetWrapper,
+  isFluentBuilder,
+  isPlainObject,
+} from "../../guards";
+
+/**
+ * Step 7: Resolves nested AssetWrapper paths
+ *
+ * This step handles cases where AssetWrapper properties are nested within
+ * interface types. It traverses paths like ["header", "left"] to find and
+ * wrap assets that should be in AssetWrapper format.
+ *
+ * @param result - The result object being built
+ * @param context - Context for nested assets
+ * @param assetWrapperPaths - Array of paths to AssetWrapper properties
+ */
+export function resolveNestedAssetWrappers<C extends BaseBuildContext>(
+  result: Record<string, unknown>,
+  context: C | undefined,
+  assetWrapperPaths: ReadonlyArray<ReadonlyArray<string>>,
+): void {
+  if (assetWrapperPaths.length === 0) {
+    return;
+  }
+
+  for (const path of assetWrapperPaths) {
+    // Skip empty paths (defensive guard against malformed metadata)
+    if (path.length === 0) {
+      continue;
+    }
+
+    // Paths with length 1 are handled by direct AssetWrapper resolution (Step 4)
+    if (path.length < 2) {
+      continue;
+    }
+
+    resolvePathInResult(result, path, context);
+  }
+}
+
+/**
+ * Resolves a specific path in the result object.
+ * Handles intermediate FluentBuilders by resolving them before continuing traversal.
+ */
+function resolvePathInResult<C extends BaseBuildContext>(
+  result: Record<string, unknown>,
+  path: ReadonlyArray<string>,
+  context: C | undefined,
+): void {
+  // Navigate to the parent object containing the AssetWrapper property
+  let current: unknown = result;
+
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+
+    if (!isPlainObject(current)) {
+      return;
+    }
+
+    let next = (current as Record<string, unknown>)[key];
+
+    if (next === undefined || next === null) {
+      return;
+    }
+
+    // If intermediate value is a builder, resolve it first
+    if (isFluentBuilder(next)) {
+      next = resolveValue(next, { context, propertyName: key });
+      (current as Record<string, unknown>)[key] = next;
+    }
+
+    current = next;
+  }
+
+  // Now `current` is the parent object, and we need to wrap the final property
+  const finalKey = path[path.length - 1];
+
+  if (!isPlainObject(current)) {
+    return;
+  }
+
+  const parent = current as Record<string, unknown>;
+  const value = parent[finalKey];
+
+  if (value === undefined || value === null) {
+    return;
+  }
+
+  // If it's already an AssetWrapper, skip
+  if (isAssetWrapper(value)) {
+    return;
+  }
+
+  // Generate slot name from the full path
+  const slotName = path.join("-");
+
+  // Handle arrays of AssetWrappers
+  if (Array.isArray(value)) {
+    parent[finalKey] = value
+      .filter((item) => item !== null && item !== undefined)
+      .map((item, index) => {
+        if (isAssetWrapper(item)) {
+          return item;
+        }
+        return resolveAndWrapAsset(item, {
+          context,
+          slotName: `${slotName}-${index}`,
+        });
+      });
+    return;
+  }
+
+  // Handle single value that needs wrapping
+  if (isFluentBuilder(value) || isAsset(value)) {
+    parent[finalKey] = resolveAndWrapAsset(value, {
+      context,
+      slotName,
+    });
+  }
+}

package/src/core/base-builder/resolution/steps/static-values.ts

@@ -0,0 +1,35 @@
+import type { BaseBuildContext } from "../../types";
+import type { ValueStorage } from "../../storage/value-storage";
+import { isAssetWrapperValue } from "../../guards";
+import { extractValue, resolveValue } from "../value-resolver";
+
+/**
+ * Step 1: Resolves static values
+ *
+ * Converts TaggedTemplateValue to strings and resolves nested FluentBuilders
+ * in static storage. AssetWrapper values are preserved for later processing.
+ *
+ * @param storage - The value storage containing static values
+ * @param result - The result object being built
+ * @param context - Optional build context
+ */
+export function resolveStaticValues<T, C extends BaseBuildContext>(
+  storage: ValueStorage<T>,
+  result: Record<string, unknown>,
+  context: C | undefined,
+): void {
+  const values = storage.getValues();
+
+  for (const [key, value] of Object.entries(values)) {
+    if (!isAssetWrapperValue(value)) {
+      // First extract any TaggedTemplateValue instances (recursively)
+      // Pass the property key to handle special cases like 'binding'
+      const extracted = extractValue(value, { propertyKey: key });
+      // Then resolve FluentBuilders and nested contexts
+      result[key] = resolveValue(extracted, { context, propertyName: key });
+    } else {
+      // Keep AssetWrapper values for later processing
+      result[key] = value;
+    }
+  }
+}

package/src/core/base-builder/resolution/steps/switches.ts

@@ -0,0 +1,71 @@
+import {
+  type BaseBuildContext,
+  type SwitchMetadata,
+  StorageKeys,
+} from "../../types";
+import type { AuxiliaryStorage } from "../../storage/auxiliary-storage";
+import { isSwitchResult } from "../../guards";
+import { setValueAtPath } from "../path-resolver";
+
+/**
+ * Step 7: Resolves switches
+ *
+ * Processes switch expressions and injects them at the specified paths.
+ * Handles both static and dynamic switches with proper ID generation.
+ *
+ * @param auxiliaryStorage - Storage containing switch metadata
+ * @param result - The result object being built
+ * @param nestedParentContext - Context for switch resolution
+ * @param arrayProperties - Set of property names that are array types
+ */
+export function resolveSwitches<C extends BaseBuildContext>(
+  auxiliaryStorage: AuxiliaryStorage,
+  result: Record<string, unknown>,
+  nestedParentContext: C | undefined,
+  arrayProperties: ReadonlySet<string>,
+): void {
+  const switches = auxiliaryStorage.getArray<SwitchMetadata<C>>(
+    StorageKeys.SWITCHES,
+  );
+  if (switches.length === 0 || !nestedParentContext) {
+    return;
+  }
+
+  let globalCaseIndex = 0;
+  switches.forEach(({ path, switchFn }) => {
+    // Create a context that includes the property/slot name for proper ID generation
+    // For path ["label"], this creates: parent-label-staticSwitch-0-text
+    // We construct the parent ID directly without registering it (no genId call)
+    const propertyName = String(path[0]);
+    const switchParentId = nestedParentContext.parentId
+      ? `${nestedParentContext.parentId}-${propertyName}`
+      : propertyName;
+
+    const switchContext = {
+      ...nestedParentContext,
+      parentId: switchParentId,
+      branch: undefined,
+    } as C;
+
+    let switchResult = switchFn(switchContext, globalCaseIndex);
+
+    // Count cases for next switch's offset
+    if (isSwitchResult(switchResult)) {
+      const switchCases =
+        switchResult.staticSwitch ?? switchResult.dynamicSwitch;
+      if (Array.isArray(switchCases)) {
+        globalCaseIndex += switchCases.length;
+      }
+    }
+
+    // If this property is an array type (e.g., actions: Array<AssetWrapper<T>>),
+    // wrap the switch result in an array to match the expected schema type.
+    // Only wrap if we're replacing the entire property (path.length === 1),
+    // not a specific element in the array (path.length > 1)
+    if (arrayProperties.has(propertyName) && path.length === 1) {
+      switchResult = [switchResult];
+    }
+
+    setValueAtPath(result, path, switchResult);
+  });
+}

package/src/core/base-builder/resolution/steps/templates.ts

@@ -0,0 +1,40 @@
+import { type BaseBuildContext, StorageKeys } from "../../types";
+import type { AuxiliaryStorage } from "../../storage/auxiliary-storage";
+import type { template as easyDslTemplate } from "../../../index";
+
+/**
+ * Step 8: Resolves templates
+ *
+ * Processes template functions and adds them to the result.
+ * Templates are special constructs that generate dynamic content.
+ *
+ * @param auxiliaryStorage - Storage containing template functions
+ * @param result - The result object being built
+ * @param context - Build context for template resolution
+ */
+export function resolveTemplates<C extends BaseBuildContext>(
+  auxiliaryStorage: AuxiliaryStorage,
+  result: Record<string, unknown>,
+  context: C | undefined,
+): void {
+  const templateFns = auxiliaryStorage.getArray<
+    ReturnType<typeof easyDslTemplate>
+  >(StorageKeys.TEMPLATES);
+
+  if (templateFns.length === 0) {
+    return;
+  }
+
+  if (!context) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        `resolveTemplates: ${templateFns.length} template(s) exist but no context provided. ` +
+          "Templates will be ignored. Pass a build context to .build() to enable template resolution.",
+      );
+    }
+    return;
+  }
+
+  const templates = templateFns.map((fn) => fn(context));
+  result.template = templates;
+}

package/src/core/base-builder/resolution/value-resolver.ts

@@ -0,0 +1,333 @@
+import type { Asset, AssetWrapper } from "@player-ui/types";
+import { BranchTypes, type BaseBuildContext } from "../types";
+import {
+  isFluentBuilder,
+  isPlainObject,
+  isAsset,
+  isAssetWrapper,
+} from "../guards";
+import { createNestedContext } from "../context";
+import { genId, peekId } from "../id/generator";
+import { isTaggedTemplateValue } from "../../tagged-template";
+
+/**
+ * Type-safe value extraction utilities for handling TaggedTemplateValue
+ * These functions properly unwrap TaggedTemplateValue while preserving structure
+ */
+
+interface ExtractValueOptions {
+  readonly propertyKey?: string;
+  readonly visited?: WeakSet<object>;
+}
+
+/**
+ * Recursively extracts values from an object, handling nested TaggedTemplateValue instances
+ */
+function extractObject<T extends Record<string, unknown>>(
+  value: T,
+  options: ExtractValueOptions,
+): T {
+  const visited = options.visited ?? new WeakSet();
+
+  if (visited.has(value)) {
+    return value;
+  }
+  visited.add(value);
+
+  const result: Record<string, unknown> = {};
+
+  for (const [key, val] of Object.entries(value)) {
+    result[key] = extractValue(val, { propertyKey: key, visited });
+  }
+
+  return result as T;
+}
+
+/**
+ * Recursively extracts values from a structure, converting TaggedTemplateValue instances
+ * to their string representations while preserving arrays and objects.
+ *
+ * **Return Type Note**: This function returns `unknown` because the input type is unknown
+ * and the transformation can change types (TaggedTemplateValue -> string). Callers should
+ * validate the returned value using type guards before using it.
+ *
+ * **Transformation Behavior**:
+ * - `TaggedTemplateValue` → `string` (via toString() or toValue())
+ * - Arrays → Arrays (elements recursively transformed)
+ * - Plain objects → Objects (properties recursively transformed)
+ * - FluentBuilder/AssetWrapper → passed through unchanged (resolved later)
+ * - Primitives → passed through unchanged
+ *
+ * @param value - The value to extract (may contain TaggedTemplateValue instances)
+ * @param options - Extraction options (propertyKey for special handling, visited for cycle detection)
+ * @returns The extracted value with TaggedTemplateValue instances converted to strings
+ *
+ * @example
+ * ```typescript
+ * const result = extractValue({ name: taggedTemplate`Hello` });
+ * // result is { name: "Hello" } but typed as unknown
+ *
+ * // Caller must validate:
+ * if (isPlainObject(result)) {
+ *   const name = result.name; // Use safely
+ * }
+ * ```
+ */
+export function extractValue(
+  value: unknown,
+  options: ExtractValueOptions = {},
+): unknown {
+  const { propertyKey, visited = new WeakSet() } = options;
+
+  // Handle TaggedTemplateValue
+  if (isTaggedTemplateValue(value)) {
+    // Special case: 'data' property (in templates) and 'binding' property should use toValue() to get raw string
+    if (propertyKey === "data" || propertyKey === "binding") {
+      return value.toValue();
+    }
+    // Default: use toString() to preserve expression/binding syntax (@[]@ and {{}})
+    return value.toString();
+  }
+
+  // Handle arrays - recursively extract each element
+  if (Array.isArray(value)) {
+    if (visited.has(value)) {
+      return value;
+    }
+    visited.add(value);
+    // Don't pass propertyKey down to array elements
+    return value.map((item) => extractValue(item, { visited }));
+  }
+
+  // Handle plain objects - recursively extract each property
+  // But skip FluentBuilders and AssetWrappers (they'll be resolved later)
+  if (
+    isPlainObject(value) &&
+    !isFluentBuilder(value) &&
+    !isAssetWrapper(value)
+  ) {
+    return extractObject(value as Record<string, unknown>, { visited });
+  }
+
+  // Return primitives and special objects as-is
+  return value;
+}
+
+/**
+ * Creates an AssetWrapper for a nested asset
+ */
+function wrapAsset<T extends Asset, C extends BaseBuildContext>(
+  asset: T,
+  context: C | undefined,
+  slotName: string,
+): AssetWrapper<T> {
+  if (!context) {
+    return { asset };
+  }
+
+  // If asset already has an ID, preserve it
+  // User-provided IDs should be respected
+  if (asset.id) {
+    return { asset: { ...asset } };
+  }
+
+  // Generate ID using slot branch for assets without IDs
+  const parentId = peekId(context);
+  const slotCtx: BaseBuildContext = {
+    parentId,
+    branch: { type: BranchTypes.SLOT, name: slotName },
+  };
+
+  return {
+    asset: {
+      ...asset,
+      id: genId(slotCtx),
+    },
+  };
+}
+
+interface ResolveValueOptions<C extends BaseBuildContext = BaseBuildContext> {
+  readonly context?: C;
+  readonly propertyName?: string;
+  readonly visited?: WeakSet<object>;
+}
+
+/**
+ * Resolves a value, handling FluentBuilders, AssetWrappers, and nested structures
+ */
+export function resolveValue<T, C extends BaseBuildContext>(
+  value: unknown,
+  options: ResolveValueOptions<C> = {},
+): unknown {
+  const { context, propertyName, visited = new WeakSet() } = options;
+
+  // Handle TaggedTemplateValue
+  if (isTaggedTemplateValue(value)) {
+    // Special case: 'data' property (in templates) and 'binding' property should use toValue() to get raw string
+    if (propertyName === "data" || propertyName === "binding") {
+      return value.toValue();
+    }
+    // Default: use toString() to preserve expression/binding syntax (@[]@ and {{}})
+    return value.toString();
+  }
+
+  // Skip null or undefined values
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  // Handle FluentBuilder instances
+  if (isFluentBuilder<T, C>(value)) {
+    return value.build(context);
+  }
+
+  // Handle AssetWrapper types - unwrap, resolve inner asset, and re-wrap
+  if (isAssetWrapper(value)) {
+    if (visited.has(value)) return value;
+    visited.add(value);
+
+    const innerAsset = value.asset;
+
+    // Resolve the inner asset if it's a builder or contains nested structures
+    const resolvedAsset = resolveValue(innerAsset, {
+      context,
+      propertyName,
+      visited,
+    });
+
+    // Return wrapped with the resolved asset
+    return { asset: resolvedAsset };
+  }
+
+  // Handle arrays - recursively resolve each element
+  if (Array.isArray(value)) {
+    if (visited.has(value)) return value;
+    visited.add(value);
+
+    // Filter out null/undefined values before processing
+    return value
+      .filter((item) => item !== null && item !== undefined)
+      .map((item, index) => {
+        const arrayContext = context
+          ? createNestedContext({
+              parentContext: context,
+              parameterName: propertyName || "array",
+              index,
+            })
+          : undefined;
+        return resolveValue(item, {
+          context: arrayContext,
+          propertyName: String(index),
+          visited,
+        });
+      });
+  }
+
+  // Handle plain objects (but not Assets - they should be terminal)
+  if (isPlainObject(value) && !isAsset(value)) {
+    if (visited.has(value)) return value;
+    visited.add(value);
+
+    const resolved: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      const nestedContext = context
+        ? createNestedContext({ parentContext: context, parameterName: key })
+        : undefined;
+      resolved[key] = resolveValue(val, {
+        context: nestedContext,
+        propertyName: key,
+        visited,
+      });
+    }
+
+    return resolved;
+  }
+
+  return value;
+}
+
+interface ResolveAndWrapAssetOptions<
+  C extends BaseBuildContext = BaseBuildContext,
+> {
+  readonly context?: C;
+  readonly slotName: string;
+  readonly visited?: WeakSet<object>;
+}
+
+/**
+ * Resolves and wraps a nested asset value
+ * This is used when we know a property should contain an AssetWrapper
+ */
+export function resolveAndWrapAsset<C extends BaseBuildContext>(
+  value: unknown,
+  options: ResolveAndWrapAssetOptions<C>,
+): AssetWrapper<Asset> | unknown {
+  const { context, slotName, visited = new WeakSet() } = options;
+
+  // Skip null or undefined values
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  // If it's already an AssetWrapper, just resolve its contents
+  if (isAssetWrapper(value)) {
+    if (visited.has(value)) return value;
+    visited.add(value);
+
+    const resolvedAsset = resolveValue(value.asset, {
+      context,
+      propertyName: slotName,
+      visited,
+    });
+    return { asset: resolvedAsset };
+  }
+
+  // If it's a FluentBuilder, we need to call it with a context that has a slot branch
+  // This ensures the built asset gets the correct ID based on the slot name
+  if (isFluentBuilder(value)) {
+    if (!context) {
+      // Without context, just build and wrap
+      const built = value.build(undefined);
+      if (isAssetWrapper(built)) {
+        return built;
+      }
+      // Only wrap if it's an Asset (has type field)
+      if (isAsset(built)) {
+        return { asset: built };
+      }
+      return built;
+    }
+
+    // Create a context with a slot branch for the builder.
+    // We use peekId to get the parent's ID without registering it, then create
+    // a slot branch context so the builder generates an ID like "parent-slotName".
+    const parentId = peekId(context);
+    const slotContext: C = {
+      ...context,
+      parentId,
+      branch: { type: BranchTypes.SLOT, name: slotName },
+    } as C;
+
+    const built = value.build(slotContext);
+
+    // If the builder produces an AssetWrapper, return it
+    if (isAssetWrapper(built)) {
+      return built;
+    }
+
+    // Only wrap if it's an Asset (has type field)
+    if (isAsset(built)) {
+      return { asset: built };
+    }
+
+    // Otherwise return as-is (for non-Asset objects like ChoiceItem)
+    return built;
+  }
+
+  // If it's an Asset, wrap it
+  if (isAsset(value)) {
+    return wrapAsset(value, context, slotName);
+  }
+
+  return resolveValue(value, { context, propertyName: slotName, visited });
+}