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

package/src/core/base-builder/conditional/index.ts

@@ -0,0 +1,64 @@
+import type { Asset } from "@player-ui/types";
+import type { FluentBuilder, BaseBuildContext } from "../types";
+import { isFluentBuilder, isAsset, isAssetWrapperValue } from "../guards";
+
+/**
+ * Resolves a value or function to its final value
+ *
+ * Generic helper that unwraps functions to their return values.
+ * Handles both simple functions and ConditionalValue types.
+ */
+export function resolveValueOrFunction<V>(value: V | (() => V)): V {
+  if (typeof value === "function" && !isFluentBuilder(value)) {
+    // SAFETY: We've checked it's a function and not a FluentBuilder,
+    // so it must be a function returning V
+    return (value as () => V)();
+  }
+
+  return value as V;
+}
+
+/**
+ * Type guard to check if a value should be wrapped in AssetWrapper format
+ */
+export function shouldWrapInAssetWrapper(
+  value: unknown,
+): value is
+  | FluentBuilder<unknown, BaseBuildContext>
+  | Asset
+  | Array<FluentBuilder<unknown, BaseBuildContext> | Asset> {
+  // Don't wrap if already wrapped (has 'asset' property but not 'type')
+  if (isAssetWrapperValue(value)) {
+    return false;
+  }
+
+  // Wrap FluentBuilders
+  if (isFluentBuilder(value)) {
+    return true;
+  }
+
+  // Wrap Assets (objects with 'type' property)
+  if (isAsset(value)) {
+    return true;
+  }
+
+  // Wrap arrays of builders/assets
+  if (Array.isArray(value) && value.length > 0) {
+    const firstItem = value[0];
+    return isFluentBuilder(firstItem) || isAsset(firstItem);
+  }
+
+  return false;
+}
+
+/**
+ * Wraps a value in AssetWrapper format if needed
+ * This enables if() and ifElse() to work with unwrapped asset builders
+ */
+export function maybeWrapAsset<V>(value: V): V | { asset: V } {
+  if (shouldWrapInAssetWrapper(value)) {
+    return { asset: value };
+  }
+
+  return value;
+}

package/src/core/base-builder/context.ts

@@ -0,0 +1,152 @@
+import { determineSlotName, genId, peekId } from "./id/generator";
+import {
+  BranchTypes,
+  type BaseBuildContext,
+  type NestedContextParams,
+  type AssetMetadata,
+} from "./types";
+
+function buildContextParams<C extends BaseBuildContext>(
+  parentContext: C,
+  parameterName: string,
+  index?: number,
+): NestedContextParams<C> {
+  const params: NestedContextParams<C> = {
+    parentContext,
+    parameterName,
+  };
+  if (index !== undefined) {
+    return { ...params, index };
+  }
+
+  return params;
+}
+
+/**
+ * Creates a nested context for child builders with automatic ID generation.
+ *
+ * 1. Determines the appropriate slot name from the parameter name
+ * 2. Generates a unique ID using the slot name
+ * 3. Creates a new context with the generated ID
+ *
+ * Use this when you want automatic ID generation for nested builders.
+ * For manual context manipulation, use object spreading directly.
+ */
+export function createNestedContext<C extends BaseBuildContext>({
+  parentContext,
+  parameterName,
+  index,
+  assetMetadata,
+}: {
+  readonly parentContext: C;
+  readonly parameterName: string;
+  readonly index?: number;
+  readonly assetMetadata?: AssetMetadata;
+}): C {
+  if (parentContext.nestedContextGenerator) {
+    const contextParams = buildContextParams(
+      parentContext,
+      parameterName,
+      index,
+    );
+    const generated = parentContext.nestedContextGenerator(contextParams);
+    // Safe assertion: nestedContextGenerator returns the same context type
+    return generated as C;
+  }
+
+  const slotName = determineSlotName(parameterName, assetMetadata);
+
+  let generatedId: string | undefined;
+  let branch: BaseBuildContext["branch"];
+
+  if (parentContext && "parentId" in parentContext) {
+    // For array items, use peekId to avoid registering the same slot multiple times
+    // For non-array items, use genId to register the slot
+    if (index !== undefined) {
+      generatedId = peekId({
+        parentId: parentContext.parentId,
+        branch: { type: BranchTypes.SLOT, name: slotName },
+      });
+      branch = { type: BranchTypes.ARRAY_ITEM, index };
+    } else {
+      generatedId = genId({
+        parentId: parentContext.parentId,
+        branch: { type: BranchTypes.SLOT, name: slotName },
+      });
+    }
+  }
+
+  const newContext: BaseBuildContext =
+    index !== undefined
+      ? {
+          ...parentContext,
+          parameterName,
+          index,
+          ...(generatedId ? { parentId: generatedId } : {}),
+          ...(assetMetadata ? { assetMetadata } : {}),
+          ...(branch ? { branch } : {}),
+        }
+      : {
+          ...parentContext,
+          parameterName,
+          ...(generatedId ? { parentId: generatedId } : {}),
+          ...(assetMetadata ? { assetMetadata } : {}),
+        };
+
+  // Safe assertion: newContext extends BaseBuildContext with additional properties
+  return newContext as C;
+}
+
+/**
+ * Creates a template context for template value generation.
+ *
+ * Template contexts use a special template branch with depth tracking
+ * to support nested templates (_index_, _index1_, _index2_, etc.).
+ */
+export function createTemplateContext<C extends BaseBuildContext>({
+  parentContext,
+  depth = 0,
+}: {
+  readonly parentContext: C;
+  readonly depth?: number;
+}): C {
+  const parentId = genId(parentContext);
+
+  const templateContext: BaseBuildContext = {
+    ...parentContext,
+    parentId,
+    branch: {
+      type: BranchTypes.TEMPLATE,
+      depth,
+    },
+  };
+
+  return templateContext as C;
+}
+
+/**
+ * Creates a switch context for switch case asset generation.
+ *
+ * Switch contexts use a special switch branch with index tracking and kind
+ * to support sequential case indexing across all switches.
+ */
+export function createSwitchContext<C extends BaseBuildContext>({
+  parentContext,
+  index,
+  kind,
+}: {
+  readonly parentContext: C;
+  readonly index: number;
+  readonly kind: "static" | "dynamic";
+}): C {
+  const switchContext: BaseBuildContext = {
+    ...parentContext,
+    branch: {
+      type: BranchTypes.SWITCH,
+      index,
+      kind,
+    },
+  };
+
+  return switchContext as C;
+}

package/src/core/base-builder/errors.ts

@@ -0,0 +1,69 @@
+/**
+ * Error codes for fluent builder errors.
+ * Use these codes for programmatic error handling.
+ */
+export const ErrorCodes = {
+  /** Context is missing when required */
+  MISSING_CONTEXT: "FLUENT_MISSING_CONTEXT",
+  /** Invalid branch type in ID generation */
+  INVALID_BRANCH: "FLUENT_INVALID_BRANCH",
+  /** Template produced no output */
+  TEMPLATE_NO_OUTPUT: "FLUENT_TEMPLATE_NO_OUTPUT",
+  /** Invalid path in value resolution */
+  INVALID_PATH: "FLUENT_INVALID_PATH",
+} as const;
+
+/**
+ * Type for error codes
+ */
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+/**
+ * Custom error class for fluent builder errors.
+ * Provides structured error information with error codes.
+ */
+export class FluentError extends Error {
+  readonly code: ErrorCode;
+  readonly context?: Record<string, unknown>;
+
+  constructor(
+    code: ErrorCode,
+    message: string,
+    context?: Record<string, unknown>,
+  ) {
+    const contextStr = context ? ` Context: ${JSON.stringify(context)}` : "";
+    super(`[${code}] ${message}${contextStr}`);
+    this.name = "FluentError";
+    this.code = code;
+    this.context = context;
+
+    // Maintains proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, FluentError);
+    }
+  }
+}
+
+/**
+ * Creates a FluentError with the given code and message.
+ * This is a convenience function for creating errors.
+ *
+ * @param code - The error code from ErrorCodes
+ * @param message - Human-readable error message
+ * @param context - Optional context object with additional details
+ * @returns A FluentError instance
+ *
+ * @example
+ * throw createFluentError(
+ *   ErrorCodes.MISSING_CONTEXT,
+ *   "Context is required for template resolution",
+ *   { templateCount: 3 }
+ * );
+ */
+export function createFluentError(
+  code: ErrorCode,
+  message: string,
+  context?: Record<string, unknown>,
+): FluentError {
+  return new FluentError(code, message, context);
+}

package/src/core/base-builder/fluent-builder-base.ts

@@ -0,0 +1,308 @@
+import type { template as easyDslTemplate } from "..";
+import {
+  type BaseBuildContext,
+  type ConditionalValue,
+  type SwitchMetadata,
+  type FluentPartial,
+  FLUENT_BUILDER_SYMBOL,
+  StorageKeys,
+} from "./types";
+import { ValueStorage } from "./storage/value-storage";
+import { AuxiliaryStorage } from "./storage/auxiliary-storage";
+import { executeBuildPipeline } from "./resolution/pipeline";
+import { resolveValueOrFunction, maybeWrapAsset } from "./conditional";
+import { switch_ } from "../switch";
+
+/**
+ * Base class for all generated builders
+ * Provides core functionality for the builder pattern with Player UI-specific features
+ *
+ * This class delegates to specialized components:
+ * - ValueStorage: Manages property values, builders, and mixed arrays
+ * - AuxiliaryStorage: Manages metadata (templates, switches)
+ * - Build Pipeline: Orchestrates the 8-step build process
+ * - Conditional Logic: Handles if/ifElse with auto-wrapping
+ */
+export abstract class FluentBuilderBase<
+  T,
+  C extends BaseBuildContext = BaseBuildContext,
+> {
+  readonly [FLUENT_BUILDER_SYMBOL]: true = true as const;
+
+  protected valueStorage: ValueStorage<T>;
+  protected auxiliaryStorage: AuxiliaryStorage;
+  protected context?: C;
+
+  /**
+   * Creates a new builder instance
+   * @param initial - Optional initial values (accepts FluentPartial for TaggedTemplateValue support)
+   */
+  constructor(initial?: FluentPartial<T, C>) {
+    this.valueStorage = new ValueStorage(initial as Partial<T>);
+    this.auxiliaryStorage = new AuxiliaryStorage();
+  }
+
+  /**
+   * Accessor for generated builders to access values
+   * This maintains backward compatibility with generated code
+   */
+  protected get values(): Partial<T> {
+    return this.valueStorage.getValues() as Partial<T>;
+  }
+
+  /**
+   * Setter for generated builders to set values in bulk
+   * Used by withAdditionalProperties() in generated builders
+   */
+  protected set values(newValues: Partial<T>) {
+    Object.entries(newValues).forEach(([key, value]) => {
+      this.valueStorage.set(key as keyof T, value);
+    });
+  }
+
+  /**
+   * Sets additional properties in bulk that may not be defined in the type schema
+   * Useful for extensibility and forward compatibility
+   */
+  public withAdditionalProperties(values: Partial<T>): this {
+    this.values = values;
+    return this;
+  }
+
+  /**
+   * Sets a property value, intelligently routing it to the appropriate storage
+   * @param key - The property key to set
+   * @param value - The value to set
+   * @returns This builder instance for chaining
+   */
+  protected set<K extends keyof T>(key: K, value: unknown): this {
+    this.valueStorage.set(key, value);
+    return this;
+  }
+
+  /**
+   * Builds the final object with defaults and nested builder resolution
+   * Executes the complete 8-step build pipeline
+   *
+   * @param defaults - Optional default values
+   * @param context - Optional build context
+   */
+  protected buildWithDefaults(defaults?: Partial<T>, context?: C): T {
+    const arrayProperties = this.getArrayPropertiesMetadata();
+    const assetWrapperPaths = this.getAssetWrapperPathsMetadata();
+    return executeBuildPipeline(
+      this.valueStorage,
+      this.auxiliaryStorage,
+      defaults,
+      context,
+      arrayProperties,
+      assetWrapperPaths,
+    );
+  }
+
+  /**
+   * Gets array property metadata from the builder class
+   * Generated builders include a static __arrayProperties__ set
+   */
+  private getArrayPropertiesMetadata(): ReadonlySet<string> {
+    const constructor = this.constructor as typeof FluentBuilderBase & {
+      __arrayProperties__?: ReadonlySet<string>;
+    };
+
+    return constructor.__arrayProperties__ ?? new Set();
+  }
+
+  /**
+   * Gets asset wrapper paths metadata from the builder class.
+   * Generated builders include a static __assetWrapperPaths__ array of paths.
+   * Each path is an array of property names leading to an AssetWrapper.
+   */
+  protected getAssetWrapperPathsMetadata(): ReadonlyArray<
+    ReadonlyArray<string>
+  > {
+    const constructor = this.constructor as typeof FluentBuilderBase & {
+      __assetWrapperPaths__?: ReadonlyArray<ReadonlyArray<string>>;
+    };
+
+    return constructor.__assetWrapperPaths__ ?? [];
+  }
+
+  /**
+   * Conditionally sets a property based on a predicate
+   *
+   * Accepts unwrapped Asset builders and automatically wraps them in AssetWrapper format.
+   *
+   * @param predicate - Function to determine if the property should be set
+   * @param property - The property key
+   * @param value - The value, builder, or function returning either
+   *
+   * @example
+   * action()
+   *   .if(() => showLabel, "label", text().withValue("Submit"))
+   */
+  public if<K extends keyof T>(
+    predicate: (builder: this) => boolean,
+    property: K,
+    value: ConditionalValue<T[K], C>,
+  ): this {
+    if (predicate(this)) {
+      const resolved = resolveValueOrFunction(value);
+      const wrapped = maybeWrapAsset(resolved);
+
+      // SAFETY: Type assertion is necessary and safe here because:
+      // 1. `maybeWrapAsset` uses type guards to check if wrapping is needed
+      // 2. For AssetWrapper properties, unwrapped builders are wrapped as { asset: builder }
+      // 3. For other properties, values pass through unchanged
+      // 4. The runtime behavior ensures type safety that TypeScript can't statically verify
+      this.set(property, wrapped as T[K]);
+    }
+
+    return this;
+  }
+
+  /**
+   * Conditionally sets a property choosing between two values
+   *
+   * Accepts unwrapped Asset builders and automatically wraps them in AssetWrapper format.
+   *
+   * @param predicate - Function to determine which value to use
+   * @param property - The property key
+   * @param trueValue - Value to use if predicate is true
+   * @param falseValue - Value to use if predicate is false
+   *
+   * @example
+   * action()
+   *   .ifElse(
+   *     () => isActive,
+   *     "label",
+   *     text().withValue("Deactivate"),
+   *     text().withValue("Activate")
+   *   )
+   */
+  public ifElse<K extends keyof T>(
+    predicate: (builder: this) => boolean,
+    property: K,
+    trueValue: ConditionalValue<T[K], C>,
+    falseValue: ConditionalValue<T[K], C>,
+  ): this {
+    const valueToUse = predicate(this) ? trueValue : falseValue;
+    const resolved = resolveValueOrFunction(valueToUse);
+    const wrapped = maybeWrapAsset(resolved);
+
+    // SAFETY: Type assertion is necessary and safe here because:
+    // 1. `maybeWrapAsset` uses type guards to check if wrapping is needed
+    // 2. For AssetWrapper properties, unwrapped builders are wrapped as { asset: builder }
+    // 3. For other properties, values pass through unchanged
+    // 4. The runtime behavior ensures type safety that TypeScript can't statically verify
+    this.set(property, wrapped as T[K]);
+    return this;
+  }
+
+  /**
+   * Checks if a property has been set
+   */
+  public has<K extends keyof T>(key: K): boolean {
+    return this.valueStorage.has(key);
+  }
+
+  /**
+   * Peeks at a property value without resolving builders
+   */
+  public peek<K extends keyof T>(key: K): T[K] | undefined {
+    return this.valueStorage.peek(key);
+  }
+
+  /**
+   * Gets builder for a property if one is set
+   */
+  public peekBuilder<K extends keyof T>(
+    key: K,
+  ): import("./types").FluentBuilder<T[K], C> | undefined {
+    return this.valueStorage.peekBuilder<K, C>(key);
+  }
+
+  /**
+   * Gets the type of value stored for a property
+   */
+  public getValueType<K extends keyof T>(
+    key: K,
+  ): "static" | "builder" | "mixed-array" | "unset" {
+    return this.valueStorage.getValueType(key);
+  }
+
+  /**
+   * Clones the builder, creating an independent copy with the same state.
+   *
+   * Note: This method requires that the builder class has a constructor that
+   * accepts an optional `initial` parameter (like all generated builders do).
+   * If your custom builder has required constructor parameters, you must
+   * override this method.
+   */
+  public clone(): this {
+    // Generated builders have constructor signature: constructor(initial?: Partial<T>)
+    // We create a new instance and copy the internal state
+    const BuilderClass = this.constructor as new (initial?: unknown) => this;
+
+    // Create new instance (passing undefined is safe for generated builders)
+    let cloned: this;
+    try {
+      cloned = new BuilderClass();
+    } catch (error) {
+      throw new Error(
+        `clone() failed: Builder class "${this.constructor.name}" requires constructor arguments. ` +
+          `Override clone() in your subclass to handle this case.`,
+      );
+    }
+
+    cloned.valueStorage = this.valueStorage.clone();
+    cloned.auxiliaryStorage = this.auxiliaryStorage.clone();
+    if (this.context) {
+      cloned.context = this.context;
+    }
+
+    return cloned;
+  }
+
+  /**
+   * Unsets a property, removing it from the builder
+   */
+  public unset<K extends keyof T>(key: K): this {
+    this.valueStorage.unset(key);
+    return this;
+  }
+
+  /**
+   * Clears all properties from the builder, resetting it to initial state
+   */
+  public clear(): this {
+    this.valueStorage.clear();
+    return this;
+  }
+
+  /**
+   * Adds a template to this builder
+   */
+  public template(templateFn: ReturnType<typeof easyDslTemplate>): this {
+    this.auxiliaryStorage.push(StorageKeys.TEMPLATES, templateFn);
+    return this;
+  }
+
+  /**
+   * Adds a switch to this builder at a specific path
+   */
+  public switch(
+    path: ReadonlyArray<string | number>,
+    switchFnArgs: Parameters<typeof switch_>[0],
+  ): this {
+    this.auxiliaryStorage.push<SwitchMetadata<C>>(StorageKeys.SWITCHES, {
+      path,
+      switchFn: switch_(switchFnArgs),
+    });
+    return this;
+  }
+
+  /**
+   * Abstract build method to be implemented by generated builders
+   */
+  abstract build(context?: C): T;
+}