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

package/src/core/base-builder/storage/auxiliary-storage.ts

@@ -0,0 +1,82 @@
+/**
+ * Manages auxiliary data storage for builders
+ *
+ * Auxiliary data is metadata that doesn't appear in the final built object
+ * but is used during the build process. This includes:
+ * - Templates (stored under "__templates__")
+ * - Switches (stored under "__switches__")
+ * - Custom metadata
+ *
+ * This separation keeps builder state clean and makes the build process more explicit
+ */
+export class AuxiliaryStorage {
+  private data: Map<string, unknown> = new Map();
+
+  /**
+   * Sets auxiliary data with a given key
+   */
+  set<T>(key: string, value: T): void {
+    this.data.set(key, value);
+  }
+
+  /**
+   * Gets auxiliary data with type assertion
+   * The caller is responsible for knowing the correct type
+   */
+  get<T>(key: string): T | undefined {
+    const value = this.data.get(key);
+    return value as T | undefined;
+  }
+
+  /**
+   * Pushes an item to an auxiliary data array
+   * Creates the array if it doesn't exist
+   */
+  push<T>(key: string, item: T): void {
+    const existing = this.data.get(key);
+    if (Array.isArray(existing)) {
+      existing.push(item);
+    } else {
+      this.data.set(key, [item]);
+    }
+  }
+
+  /**
+   * Gets an auxiliary data array
+   * Returns empty array if doesn't exist or isn't an array
+   */
+  getArray<T>(key: string): T[] {
+    const existing = this.data.get(key);
+    return Array.isArray(existing) ? existing : [];
+  }
+
+  /**
+   * Checks if auxiliary data exists for a key
+   */
+  has(key: string): boolean {
+    return this.data.has(key);
+  }
+
+  /**
+   * Deletes auxiliary data for a key
+   */
+  delete(key: string): boolean {
+    return this.data.delete(key);
+  }
+
+  /**
+   * Clears all auxiliary data
+   */
+  clear(): void {
+    this.data.clear();
+  }
+
+  /**
+   * Clones the auxiliary storage, creating an independent copy
+   */
+  clone(): AuxiliaryStorage {
+    const cloned = new AuxiliaryStorage();
+    cloned.data = new Map(this.data);
+    return cloned;
+  }
+}

package/src/core/base-builder/storage/value-storage.ts

@@ -0,0 +1,282 @@
+import type {
+  BaseBuildContext,
+  FluentBuilder,
+  MixedArrayMetadata,
+} from "../types";
+import { isFluentBuilder } from "../guards";
+
+/**
+ * Manages storage for builder property values
+ *
+ * Values are stored in three different maps based on their type:
+ * - values: Static values (strings, numbers, plain objects without builders)
+ * - builders: FluentBuilder instances and objects containing builders
+ * - mixedArrays: Arrays containing both static values and builders
+ *
+ * This separation allows efficient resolution during the build process
+ */
+export class ValueStorage<T> {
+  private values: Partial<T> = {};
+  private builders: Map<
+    string,
+    FluentBuilder<unknown, BaseBuildContext> | Record<string, unknown>
+  > = new Map();
+  private mixedArrays: Map<string, MixedArrayMetadata> = new Map();
+
+  constructor(initial?: Partial<T>) {
+    if (initial) {
+      Object.entries(initial).forEach(([key, value]) => {
+        this.set(key as keyof T, value);
+      });
+    }
+  }
+
+  /**
+   * Sets a property value, intelligently routing it to the appropriate storage
+   *
+   * This method performs runtime type checking to determine how to store the value:
+   * - FluentBuilder instances → builders Map
+   * - Arrays with builders → mixedArrays Map
+   * - Objects with builders → builders Map
+   * - Everything else → values (static storage)
+   */
+  set<K extends keyof T>(key: K, value: unknown): void {
+    const keyStr = String(key);
+
+    if (isFluentBuilder(value)) {
+      this.builders.set(keyStr, value);
+      delete this.values[key];
+      this.mixedArrays.delete(keyStr);
+    } else if (Array.isArray(value)) {
+      this.handleArrayValue(key, keyStr, value);
+    } else if (
+      typeof value === "object" &&
+      value !== null &&
+      this.containsBuilder(value)
+    ) {
+      this.builders.set(keyStr, value as Record<string, unknown>);
+      delete this.values[key];
+      this.mixedArrays.delete(keyStr);
+    } else {
+      this.setStaticValue(key, keyStr, value);
+    }
+  }
+
+  /**
+   * Handles array value storage, detecting mixed arrays with builders
+   */
+  private handleArrayValue<K extends keyof T>(
+    key: K,
+    keyStr: string,
+    value: readonly unknown[],
+  ): void {
+    const builderIndices = new Set<number>();
+    const objectIndices = new Set<number>();
+
+    value.forEach((item, index) => {
+      if (isFluentBuilder(item)) {
+        builderIndices.add(index);
+      } else if (
+        typeof item === "object" &&
+        item !== null &&
+        this.containsBuilder(item)
+      ) {
+        objectIndices.add(index);
+      }
+    });
+
+    const hasBuilders = builderIndices.size > 0 || objectIndices.size > 0;
+
+    if (hasBuilders) {
+      this.mixedArrays.set(keyStr, {
+        array: value,
+        builderIndices,
+        objectIndices,
+      });
+      delete this.values[key];
+    } else {
+      this.setStaticValue(key, keyStr, value);
+      this.mixedArrays.delete(keyStr);
+    }
+
+    this.builders.delete(keyStr);
+  }
+
+  /**
+   * Sets a static value with proper type handling
+   */
+  private setStaticValue<K extends keyof T>(
+    key: K,
+    keyStr: string,
+    value: unknown,
+  ): void {
+    // For known types in T, TypeScript will validate at compile time
+    // At runtime, we trust the caller has provided a compatible type
+    this.values[key] = value as T[K];
+    this.builders.delete(keyStr);
+    this.mixedArrays.delete(keyStr);
+  }
+
+  /**
+   * Checks if an object contains any builders recursively
+   * Handles circular references gracefully
+   */
+  private containsBuilder(
+    obj: unknown,
+    visited: WeakSet<object> = new WeakSet(),
+  ): boolean {
+    if (isFluentBuilder(obj)) return true;
+
+    if (!obj || typeof obj !== "object") return false;
+
+    if (visited.has(obj)) return false;
+    visited.add(obj);
+
+    if (Array.isArray(obj)) {
+      return obj.some((item) => this.containsBuilder(item, visited));
+    }
+
+    const proto = Object.getPrototypeOf(obj);
+    if (proto === Object.prototype || proto === null) {
+      return Object.values(obj).some((val) =>
+        this.containsBuilder(val, visited),
+      );
+    }
+
+    return false;
+  }
+
+  /**
+   * Checks if a property has been set
+   */
+  has<K extends keyof T>(key: K): boolean {
+    const keyStr = String(key);
+    return (
+      key in this.values ||
+      this.builders.has(keyStr) ||
+      this.mixedArrays.has(keyStr)
+    );
+  }
+
+  /**
+   * Peeks at a property value without resolving builders
+   * Returns the raw value if it's static, the array if it's mixed, or undefined if it's a builder
+   */
+  peek<K extends keyof T>(key: K): T[K] | undefined {
+    const keyStr = String(key);
+
+    const mixedArray = this.mixedArrays.get(keyStr);
+    if (mixedArray) {
+      return mixedArray.array as T[K];
+    }
+
+    if (this.builders.has(keyStr)) {
+      return undefined;
+    }
+
+    return this.values[key];
+  }
+
+  /**
+   * Gets builder for a property if one is set
+   */
+  peekBuilder<K extends keyof T, C extends BaseBuildContext>(
+    key: K,
+  ): FluentBuilder<T[K], C> | undefined {
+    const keyStr = String(key);
+    const entry = this.builders.get(keyStr);
+    if (!entry) return undefined;
+
+    if (isFluentBuilder<T[K], C>(entry)) {
+      return entry;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Gets the type of value stored for a property
+   */
+  getValueType<K extends keyof T>(
+    key: K,
+  ): "static" | "builder" | "mixed-array" | "unset" {
+    const keyStr = String(key);
+
+    if (this.mixedArrays.has(keyStr)) {
+      return "mixed-array";
+    }
+
+    if (this.builders.has(keyStr)) {
+      return "builder";
+    }
+
+    if (key in this.values) {
+      return "static";
+    }
+
+    return "unset";
+  }
+
+  /**
+   * Gets all static values for the build pipeline
+   */
+  getValues(): Readonly<Partial<T>> {
+    return this.values;
+  }
+
+  /**
+   * Gets all builder entries for the build pipeline
+   */
+  getBuilders(): ReadonlyMap<
+    string,
+    FluentBuilder<unknown, BaseBuildContext> | Record<string, unknown>
+  > {
+    return this.builders;
+  }
+
+  /**
+   * Gets all mixed array entries for the build pipeline
+   */
+  getMixedArrays(): ReadonlyMap<string, MixedArrayMetadata> {
+    return this.mixedArrays;
+  }
+
+  /**
+   * Unsets a property, removing it from storage
+   */
+  unset<K extends keyof T>(key: K): void {
+    const keyStr = String(key);
+    delete this.values[key];
+    this.builders.delete(keyStr);
+    this.mixedArrays.delete(keyStr);
+  }
+
+  /**
+   * Clears all properties from storage
+   */
+  clear(): void {
+    this.values = {};
+    this.builders.clear();
+    this.mixedArrays.clear();
+  }
+
+  /**
+   * Clones the storage, creating an independent copy
+   */
+  clone(): ValueStorage<T> {
+    const cloned = new ValueStorage<T>();
+    cloned.values = { ...this.values };
+    cloned.builders = new Map(this.builders);
+    cloned.mixedArrays = new Map(
+      Array.from(this.mixedArrays.entries()).map(([key, metadata]) => [
+        key,
+        {
+          array: metadata.array,
+          builderIndices: new Set(metadata.builderIndices),
+          objectIndices: new Set(metadata.objectIndices),
+        },
+      ]),
+    );
+    return cloned;
+  }
+}

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

@@ -0,0 +1,266 @@
+import { Asset, AssetWrapper } from "@player-ui/types";
+import type { TaggedTemplateValue } from "../tagged-template/types";
+
+/**
+ * Unique symbol to identify FluentBuilder instances
+ * Used for runtime type checking of builder objects
+ */
+export const FLUENT_BUILDER_SYMBOL: unique symbol =
+  Symbol.for("fluent-builder");
+
+/**
+ * Constants for branch type discriminators
+ * Use these instead of string literals to prevent typos
+ */
+export const BranchTypes = {
+  SLOT: "slot",
+  ARRAY_ITEM: "array-item",
+  TEMPLATE: "template",
+  SWITCH: "switch",
+  CUSTOM: "custom",
+} as const;
+
+/**
+ * Constants for internal storage keys
+ * Used by AuxiliaryStorage to store templates and switches
+ */
+export const StorageKeys = {
+  TEMPLATES: "__templates__",
+  SWITCHES: "__switches__",
+} as const;
+
+/**
+ * Constants for common property keys used in asset building
+ */
+export const PropertyKeys = {
+  ID: "id",
+  TYPE: "type",
+  VALUE: "value",
+  BINDING: "binding",
+} as const;
+
+/**
+ * Core interface for all fluent builders
+ * Provides build(), peek(), and has() methods for all builder types
+ */
+export interface FluentBuilder<
+  T,
+  C extends BaseBuildContext = BaseBuildContext,
+> {
+  readonly [FLUENT_BUILDER_SYMBOL]: true;
+  build(context?: C): T;
+  peek<K extends keyof T>(key: K): T[K] | undefined;
+  has<K extends keyof T>(key: K): boolean;
+}
+
+/**
+ * Type-erased asset builder interface for generic asset handling
+ */
+export type AnyAssetBuilder<C extends BaseBuildContext = BaseBuildContext> = {
+  readonly [FLUENT_BUILDER_SYMBOL]: true;
+  build(context?: C): Asset;
+  peek(key: string): unknown;
+  has(key: string): boolean;
+};
+
+/**
+ * Parameters for creating nested build contexts
+ * Used by nested context generators to create child contexts
+ */
+export interface NestedContextParams<C extends BaseBuildContext> {
+  readonly parentContext: C;
+  readonly parameterName: string;
+  readonly index?: number;
+}
+
+/**
+ * Function type for custom nested context generation
+ * Allows users to customize how child contexts are created
+ */
+export type NestedContextGenerator<C extends BaseBuildContext> = (
+  params: NestedContextParams<C>,
+) => C;
+
+/**
+ * Metadata about an asset used for ID generation and context tracking
+ */
+export interface AssetMetadata {
+  readonly type?: string;
+  readonly binding?: string;
+  readonly value?: string;
+}
+
+/**
+ * Base build context interface containing common fields for all builders
+ * Extended by specific builder implementations for custom context needs
+ */
+export interface BaseBuildContext {
+  readonly parentId?: string;
+  readonly parameterName?: string;
+  readonly index?: number;
+  readonly branch?: IdBranch;
+  readonly nestedContextGenerator?: NestedContextGenerator<BaseBuildContext>;
+  readonly assetMetadata?: AssetMetadata;
+  readonly [key: string]: unknown;
+}
+
+/**
+ * Slot branch for named properties (e.g., "label", "action")
+ * Creates IDs like: parent-label, parent-action
+ */
+export interface SlotBranch {
+  type: "slot";
+  name: string;
+}
+
+/**
+ * Array item branch for indexed elements
+ * Creates IDs like: parent-0, parent-1
+ */
+export interface ArrayItemBranch {
+  type: "array-item";
+  index: number;
+}
+
+/**
+ * Template branch for template placeholders
+ * Creates IDs like: parent-_index_, parent-_index1_
+ */
+export interface TemplateBranch {
+  type: "template";
+  depth?: number;
+}
+
+/**
+ * Switch branch for conditional cases
+ * Creates IDs like: parent-staticSwitch-0, parent-dynamicSwitch-1
+ */
+export interface SwitchBranch {
+  type: "switch";
+  index: number;
+  kind: "static" | "dynamic";
+}
+
+/**
+ * Custom branch for user-defined ID patterns
+ */
+export interface CustomBranch {
+  type: "custom";
+}
+
+/**
+ * Union of all branch types for type-safe ID generation
+ */
+export type IdBranch =
+  | SlotBranch
+  | ArrayItemBranch
+  | TemplateBranch
+  | SwitchBranch
+  | CustomBranch;
+
+/**
+ * Metadata for arrays containing mixed static values and builders
+ * Tracks which indices contain builders for selective resolution
+ */
+export interface MixedArrayMetadata {
+  readonly array: readonly unknown[];
+  readonly builderIndices: ReadonlySet<number>;
+  readonly objectIndices: ReadonlySet<number>;
+}
+
+/**
+ * Metadata for template storage in FluentBuilderBase
+ */
+export interface TemplateMetadata {
+  readonly data: string;
+  readonly output: string;
+  readonly dynamic?: boolean;
+}
+
+/**
+ * Path type for targeting where to inject values in nested structures
+ * Example: ["actions", 0, "label"] targets actions[0].label
+ */
+export type ValuePath = ReadonlyArray<string | number>;
+
+/**
+ * Metadata for switch storage in FluentBuilderBase
+ */
+export interface SwitchMetadata<C extends BaseBuildContext = BaseBuildContext> {
+  readonly path: ValuePath;
+  readonly switchFn: (context: C, globalCaseIndex?: number) => unknown;
+}
+
+/**
+ * Helper type for conditional property values in if/ifElse methods
+ * Allows passing unwrapped Asset builders to AssetWrapper properties
+ * Enables: .if(() => true, "label", text().withValue("..."))
+ * Instead of: .if(() => true, "label", { asset: text().withValue("...") })
+ */
+export type ConditionalValue<T, C extends BaseBuildContext> =
+  // Case 1: Single AssetWrapper<A> property
+  T extends AssetWrapper<infer A> | undefined
+    ?
+        | T
+        | FluentBuilder<T, C>
+        | FluentBuilder<A, C>
+        | A
+        | Array<FluentBuilder<A, C> | A>
+        | (() =>
+            | T
+            | FluentBuilder<T, C>
+            | FluentBuilder<A, C>
+            | A
+            | Array<FluentBuilder<A, C> | A>)
+    : // Case 2: Array<AssetWrapper<A>> property
+      T extends Array<AssetWrapper<infer A>>
+      ?
+          | T
+          | Array<
+              | AssetWrapper<A>
+              | FluentBuilder<AssetWrapper<A>, C>
+              | FluentBuilder<A, C>
+              | A
+            >
+          | (() =>
+              | T
+              | Array<
+                  | AssetWrapper<A>
+                  | FluentBuilder<AssetWrapper<A>, C>
+                  | FluentBuilder<A, C>
+                  | A
+                >)
+      : // Case 3: Other properties
+        T | FluentBuilder<T, C> | (() => T | FluentBuilder<T, C>);
+
+/**
+ * Transforms property types to allow TaggedTemplateValue for scalars
+ * and FluentBuilder for AssetWrapper properties.
+ */
+export type FluentPartialValue<
+  T,
+  C extends BaseBuildContext = BaseBuildContext,
+> = T extends string
+  ? T | TaggedTemplateValue<string>
+  : T extends number
+    ? T | TaggedTemplateValue<number>
+    : T extends boolean
+      ? T | TaggedTemplateValue<boolean>
+      : T extends bigint
+        ? T | TaggedTemplateValue<bigint>
+        : T extends AssetWrapper<infer A>
+          ? T | FluentBuilder<A, C> | A
+          : T extends Array<AssetWrapper<infer A>>
+            ? Array<AssetWrapper<A> | FluentBuilder<A, C> | A>
+            : T extends Array<infer E>
+              ? Array<FluentPartialValue<E, C>>
+              : T extends object
+                ? { [K in keyof T]: FluentPartialValue<T[K], C> }
+                : T;
+
+/**
+ * Partial type for builder constructors that allows TaggedTemplateValue for scalars.
+ */
+export type FluentPartial<T, C extends BaseBuildContext = BaseBuildContext> = {
+  [K in keyof T]?: FluentPartialValue<T[K], C>;
+};

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

@@ -0,0 +1,10 @@
+export function createInspectMethod(
+  builderName: string,
+  properties: Record<string, unknown>,
+): string {
+  return `${builderName} { properties: ${JSON.stringify(
+    properties,
+    null,
+    2,
+  )} }`;
+}