@player-tools/fluent 0.13.0--canary.221.5662

package/src/core/base-builder/__tests__/template.test.ts

@@ -0,0 +1,449 @@
+import { describe, test, expect, beforeEach } from "vitest";
+import type { Template, Asset } from "@player-ui/types";
+import { template, isTemplate, TEMPLATE_MARKER } from "../../template";
+import {
+  type BaseBuildContext,
+  type SlotBranch,
+  resetGlobalIdSet,
+} from "../index";
+import { text } from "../../mocks";
+import { binding as b } from "../../tagged-template";
+
+// Mock BaseBuildContext
+const mockParentCtx: BaseBuildContext = {
+  parentId: "parent-1",
+  branch: {
+    type: "slot",
+    name: "test",
+  } as SlotBranch,
+};
+
+describe("template integration with base-builder", () => {
+  beforeEach(() => {
+    resetGlobalIdSet();
+  });
+
+  test("create a basic template configuration", () => {
+    const result = template({
+      data: "list.of.names",
+      output: "values",
+      value: text().withValue(b`list.of.names._index_`),
+    })(mockParentCtx);
+
+    const expected: Template<{ asset: Asset<"text"> }> = {
+      data: "list.of.names",
+      output: "values",
+      value: {
+        asset: {
+          id: "parent-1-test-_index_-text",
+          type: "text",
+          value: "{{list.of.names._index_}}",
+        },
+      },
+    };
+
+    expect(result).toEqual(expected);
+  });
+
+  test("create a template with tagged template binding", () => {
+    const result = template({
+      data: b`list.of.names`,
+      output: "values",
+      value: text().withValue(b`list.of.names._index_`),
+    })(mockParentCtx);
+
+    const expected: Template<{ asset: Asset<"text"> }> = {
+      data: "{{list.of.names}}",
+      output: "values",
+      value: {
+        asset: {
+          id: "parent-1-test-_index_-text",
+          type: "text",
+          value: "{{list.of.names._index_}}",
+        },
+      },
+    };
+
+    expect(result).toEqual(expected);
+  });
+
+  test("include dynamic flag when specified", () => {
+    const result = template({
+      data: "list.of.names",
+      output: "values",
+      dynamic: true,
+      value: text().withValue(b`list.of.names._index_`),
+    })(mockParentCtx);
+
+    const expected: Template<{ asset: Asset<"text"> }> = {
+      data: "list.of.names",
+      output: "values",
+      dynamic: true,
+      value: {
+        asset: {
+          id: "parent-1-test-_index_-text",
+          type: "text",
+          value: "{{list.of.names._index_}}",
+        },
+      },
+    };
+
+    expect(result).toEqual(expected);
+  });
+
+  test("not include dynamic flag when it is false", () => {
+    const result = template({
+      data: "list.of.names",
+      output: "values",
+      dynamic: false,
+      value: text().withValue(b`list.of.names._index_`),
+    })(mockParentCtx);
+
+    const expected: Template<{ asset: Asset<"text"> }> = {
+      data: "list.of.names",
+      output: "values",
+      value: {
+        asset: {
+          id: "parent-1-test-_index_-text",
+          type: "text",
+          value: "{{list.of.names._index_}}",
+        },
+      },
+    };
+
+    expect(result).toEqual(expected);
+    expect(result).not.toHaveProperty("dynamic");
+  });
+
+  test("pass the correct parent context to the value function", () => {
+    let capturedParentCtx: BaseBuildContext | null = null;
+
+    const valueWithCapture = (parentCtx: BaseBuildContext): Asset<"text"> => {
+      capturedParentCtx = parentCtx;
+      return {
+        id: "test",
+        type: "text",
+        value: "test",
+      };
+    };
+
+    template({
+      data: "list.of.names",
+      output: "values",
+      value: valueWithCapture,
+    })(mockParentCtx);
+
+    expect(capturedParentCtx).toEqual({
+      parentId: "parent-1-test",
+      branch: {
+        type: "template",
+        depth: 0,
+      },
+    });
+  });
+
+  // Simulation of a multiple templates scenario (we test the output structure, not runtime behavior)
+  test("support the structure for multiple templates with the same output property", () => {
+    const template1 = template({
+      data: "list.of.names",
+      output: "values",
+      value: text().withValue(b`list.of.names._index_`),
+    })(mockParentCtx);
+
+    const template2 = template({
+      data: "list.of.other-names",
+      output: "values",
+      value: text().withValue(b`list.of.other-names._index_`),
+    })(mockParentCtx);
+
+    expect(template1.output).toEqual(template2.output);
+    expect(template1.output).toBe("values");
+  });
+
+  // Test complex nested asset structures
+  test("handle complex nested asset structures", () => {
+    interface CollectionAsset extends Asset<"collection"> {
+      items: Array<{ asset: Asset<"text"> }>;
+    }
+
+    const collectionAsset = (): CollectionAsset => ({
+      id: "collection-_index_",
+      type: "collection",
+      items: [
+        {
+          asset: {
+            id: "item-_index_-0",
+            type: "text",
+            value: "{{list.of.names._index_.first}}",
+          },
+        },
+        {
+          asset: {
+            id: "item-_index_-1",
+            type: "text",
+            value: "{{list.of.names._index_.last}}",
+          },
+        },
+      ],
+    });
+
+    const result = template({
+      data: "list.of.names",
+      output: "collections",
+      value: collectionAsset,
+    })(mockParentCtx);
+
+    const expected: Template<{ asset: CollectionAsset }> = {
+      data: "list.of.names",
+      output: "collections",
+      value: {
+        asset: {
+          id: "collection-_index_",
+          type: "collection",
+          items: [
+            {
+              asset: {
+                id: "item-_index_-0",
+                type: "text",
+                value: "{{list.of.names._index_.first}}",
+              },
+            },
+            {
+              asset: {
+                id: "item-_index_-1",
+                type: "text",
+                value: "{{list.of.names._index_.last}}",
+              },
+            },
+          ],
+        },
+      },
+    };
+
+    expect(result).toEqual(expected);
+  });
+
+  // Test the structure for dynamic template functionality
+  test("create a dynamic template that updates when data changes", () => {
+    const result = template({
+      data: "list.of.names",
+      output: "values",
+      dynamic: true,
+      value: text().withValue(b`list.of.names._index_`),
+    })(mockParentCtx);
+
+    expect(result.dynamic).toBe(true);
+  });
+});
+
+describe("isTemplate type guard", () => {
+  beforeEach(() => {
+    resetGlobalIdSet();
+  });
+
+  test("should return true for template functions", () => {
+    const templateFn = template({
+      data: "list.of.names",
+      output: "values",
+      value: text().withValue(b`list.of.names._index_`),
+    });
+
+    expect(isTemplate(templateFn)).toBe(true);
+  });
+
+  test("should return false for non-template functions", () => {
+    const regularFunction = () => ({});
+    const arrowFunction = () => "test";
+    const objectWithFunction = { fn: () => {} };
+
+    expect(isTemplate(regularFunction)).toBe(false);
+    expect(isTemplate(arrowFunction)).toBe(false);
+    expect(isTemplate(objectWithFunction.fn)).toBe(false);
+  });
+
+  test("should return false for non-functions", () => {
+    const string = "not a function";
+    const number = 42;
+    const object = { type: "test" };
+    const nullValue = null;
+    const undefinedValue = undefined;
+
+    expect(isTemplate(string)).toBe(false);
+    expect(isTemplate(number)).toBe(false);
+    expect(isTemplate(object)).toBe(false);
+    expect(isTemplate(nullValue)).toBe(false);
+    expect(isTemplate(undefinedValue)).toBe(false);
+  });
+
+  test("should have TEMPLATE_MARKER symbol on template functions", () => {
+    const templateFn = template({
+      data: "list.of.names",
+      output: "values",
+      value: text().withValue(b`list.of.names._index_`),
+    });
+
+    expect(TEMPLATE_MARKER in templateFn).toBe(true);
+    expect(
+      (templateFn as unknown as { [TEMPLATE_MARKER]: unknown })[
+        TEMPLATE_MARKER
+      ],
+    ).toBe(true);
+  });
+
+  test("should not have TEMPLATE_MARKER symbol on regular functions", () => {
+    const regularFunction = () => ({});
+
+    expect(TEMPLATE_MARKER in regularFunction).toBe(false);
+  });
+
+  test("should work with template functions that have been called", () => {
+    const templateFn = template({
+      data: "list.of.names",
+      output: "values",
+      value: text().withValue(b`list.of.names._index_`),
+    });
+
+    // Call the template function
+    templateFn(mockParentCtx);
+
+    // The original function should still be identifiable as a template
+    expect(isTemplate(templateFn)).toBe(true);
+    expect(TEMPLATE_MARKER in templateFn).toBe(true);
+  });
+});
+
+describe("template with optional output", () => {
+  beforeEach(() => {
+    resetGlobalIdSet();
+  });
+
+  test("should infer output from slot context", () => {
+    const contextWithSlot: BaseBuildContext = {
+      parentId: "parent-1",
+      branch: {
+        type: "slot",
+        name: "values-0", // This should infer "values" as the output
+      },
+    };
+
+    const templateFn = template({
+      data: b`list.of.names`,
+      // No output provided - should be inferred
+      value: text().withValue(b`list.of.names._index_`),
+    });
+
+    const result = templateFn(contextWithSlot);
+
+    expect(result.output).toBe("values");
+    expect(result.data).toBe("{{list.of.names}}");
+  });
+
+  test("should throw error when output cannot be inferred", () => {
+    const contextWithoutSlot: BaseBuildContext = {
+      parentId: "parent-1",
+      branch: {
+        type: "template",
+        depth: 0,
+      },
+    };
+
+    const templateFn = template({
+      data: b`list.of.names`,
+      // No output provided and context doesn't allow inference
+      value: text().withValue(b`list.of.names._index_`),
+    });
+
+    expect(() => templateFn(contextWithoutSlot)).toThrow(
+      "Template output must be provided or inferrable from context",
+    );
+  });
+
+  test("should use explicit output when provided", () => {
+    const contextWithSlot: BaseBuildContext = {
+      parentId: "parent-1",
+      branch: {
+        type: "slot",
+        name: "values-0",
+      },
+    };
+
+    const templateFn = template({
+      data: b`list.of.names`,
+      output: "customOutput", // Explicit output should override inference
+      value: text().withValue(b`list.of.names._index_`),
+    });
+
+    const result = templateFn(contextWithSlot);
+
+    expect(result.output).toBe("customOutput");
+  });
+});
+
+describe("template context creation", () => {
+  beforeEach(() => {
+    resetGlobalIdSet();
+  });
+
+  test("should create template context with depth 0", () => {
+    const context: BaseBuildContext = {
+      parentId: "parent",
+    };
+
+    const templateFn = template({
+      data: "items",
+      output: "values",
+      value: (ctx: BaseBuildContext) => {
+        // Verify the context has template branch
+        expect(ctx.branch).toEqual({ type: "template", depth: 0 });
+        expect(ctx.parentId).toBe("parent");
+
+        return {
+          id: "test",
+          type: "text",
+          value: "test",
+        };
+      },
+    });
+
+    templateFn(context);
+  });
+
+  test("should generate proper template IDs with _index_ placeholder", () => {
+    const context: BaseBuildContext = {
+      parentId: "parent",
+    };
+
+    const result = template({
+      data: "items",
+      output: "values",
+      value: text({ value: "test" }),
+    })(context);
+
+    expect(result.value.asset.id).toBe("parent-_index_-text");
+  });
+
+  test("should support nested template depth tracking", () => {
+    const context: BaseBuildContext = {
+      parentId: "parent",
+    };
+
+    // First level template
+    const level1Result = template({
+      data: "items",
+      output: "values",
+      value: text({ value: "test" }),
+    })(context);
+
+    expect(level1Result.value.asset.id).toBe("parent-_index_-text");
+
+    // Simulate nested template (depth 1)
+    const nestedContext: BaseBuildContext = {
+      parentId: "parent-item",
+      branch: { type: "template", depth: 1 },
+    };
+
+    const nestedAsset = text({ value: "nested" }).build(nestedContext);
+
+    expect(nestedAsset.id).toBe("parent-item-_index1_-text");
+  });
+});

package/src/core/base-builder/__tests__/value-extraction.test.ts

@@ -0,0 +1,200 @@
+import { describe, test, expect, beforeEach } from "vitest";
+import { action } from "../../mocks/generated";
+import { binding as b, expression as e } from "../../tagged-template";
+import { resetGlobalIdSet } from "../index";
+
+/**
+ * Test suite for value extraction with TaggedTemplateValue
+ * Ensures that arrays and objects with TaggedTemplateValue are properly extracted
+ * without being stringified to [object Object] or flattened
+ */
+
+describe("Value Extraction - TaggedTemplateValue Handling", () => {
+  beforeEach(() => {
+    resetGlobalIdSet();
+  });
+
+  test("preserves array structure with TaggedTemplateValue elements", () => {
+    const asset = action()
+      .withExp([
+        e`conditional(isEmpty({{forms.test}}), setDataVal('forms.test', ''), 'false')`,
+        e`conditional(isEmpty({{forms.other}}), setDataVal('forms.other', ''), 'false')`,
+      ])
+      .build({ parentId: "view-1" });
+
+    expect(asset.exp).toBeInstanceOf(Array);
+    expect(asset.exp).toHaveLength(2);
+    // Expressions should preserve @[]@ syntax
+    expect(asset.exp?.[0]).toBe(
+      "@[conditional(isEmpty({{forms.test}}), setDataVal('forms.test', ''), 'false')]@",
+    );
+    expect(asset.exp?.[1]).toBe(
+      "@[conditional(isEmpty({{forms.other}}), setDataVal('forms.other', ''), 'false')]@",
+    );
+  });
+
+  test("preserves array structure with mixed TaggedTemplateValue and strings", () => {
+    const asset = action()
+      .withExp([
+        "static string",
+        e`conditional(isEmpty({{forms.test}}), setDataVal('forms.test', ''), 'false')`,
+      ])
+      .build({ parentId: "view-1" });
+
+    expect(asset.exp).toBeInstanceOf(Array);
+    expect(asset.exp).toHaveLength(2);
+    expect(asset.exp?.[0]).toBe("static string");
+    // Expression should preserve @[]@ syntax
+    expect(asset.exp?.[1]).toBe(
+      "@[conditional(isEmpty({{forms.test}}), setDataVal('forms.test', ''), 'false')]@",
+    );
+  });
+
+  test("extracts object with TaggedTemplateValue properties correctly", () => {
+    const asset = action()
+      .withConfirmation({
+        message: b`forms.confirmMessage`,
+        affirmativeLabel: b`forms.yesLabel`,
+        negativeLabel: "Cancel",
+      })
+      .build({ parentId: "view-1" });
+
+    // Bindings should preserve {{}} syntax
+    expect(asset.confirmation).toEqual({
+      message: "{{forms.confirmMessage}}",
+      affirmativeLabel: "{{forms.yesLabel}}",
+      negativeLabel: "Cancel",
+    });
+
+    // Ensure it's not stringified to [object Object]
+    expect(typeof asset.confirmation).toBe("object");
+    expect(asset.confirmation).not.toBe("[object Object]");
+  });
+
+  test("handles nested arrays in objects with TaggedTemplateValue", () => {
+    // Simulate a complex structure with nested arrays
+    const asset = action()
+      .withAdditionalProperties({
+        listeners: {
+          "dataChange.forms.test": [
+            e`conditional(isEmpty({{forms.test}}), setDataVal('forms.test', ''), 'false')`,
+          ],
+          "dataChange.forms.other": [
+            e`setDataVal('forms.other', 'value1')`,
+            e`setDataVal('forms.other2', 'value2')`,
+          ],
+        },
+      })
+      .build({ parentId: "view-1" });
+
+    // Check listeners object exists and is not stringified
+    expect(asset.listeners).toBeDefined();
+    expect(typeof asset.listeners).toBe("object");
+    expect(asset.listeners).not.toBe("[object Object]");
+
+    // Check nested arrays are preserved with expression syntax
+    const listeners = asset.listeners as Record<string, string[]>;
+    expect(Array.isArray(listeners["dataChange.forms.test"])).toBe(true);
+    expect(listeners["dataChange.forms.test"]).toHaveLength(1);
+    expect(listeners["dataChange.forms.test"][0]).toBe(
+      "@[conditional(isEmpty({{forms.test}}), setDataVal('forms.test', ''), 'false')]@",
+    );
+
+    expect(Array.isArray(listeners["dataChange.forms.other"])).toBe(true);
+    expect(listeners["dataChange.forms.other"]).toHaveLength(2);
+    expect(listeners["dataChange.forms.other"][0]).toBe(
+      "@[setDataVal('forms.other', 'value1')]@",
+    );
+    expect(listeners["dataChange.forms.other"][1]).toBe(
+      "@[setDataVal('forms.other2', 'value2')]@",
+    );
+  });
+
+  test("handles nested objects with TaggedTemplateValue in arrays", () => {
+    // Simulate modifiers array with objects
+    const asset = action()
+      .withAdditionalProperties({
+        modifiers: [
+          { type: "tag", value: b`forms.tagValue` },
+          { type: "style", value: "important" },
+        ],
+      })
+      .build({ parentId: "view-1" });
+
+    expect(asset.modifiers).toBeDefined();
+    expect(Array.isArray(asset.modifiers)).toBe(true);
+
+    const modifiers = asset.modifiers as Array<{ type: string; value: string }>;
+    expect(modifiers).toHaveLength(2);
+
+    // First modifier should have extracted TaggedTemplateValue with binding syntax
+    expect(modifiers[0]).toEqual({ type: "tag", value: "{{forms.tagValue}}" });
+    expect(modifiers[0]).not.toBe("[object Object]");
+
+    // Second modifier should be unchanged
+    expect(modifiers[1]).toEqual({ type: "style", value: "important" });
+    expect(modifiers[1]).not.toBe("[object Object]");
+  });
+
+  test("handles empty metadata object correctly", () => {
+    const asset = action().withMetaData({}).build({ parentId: "view-1" });
+
+    expect(asset.metaData).toEqual({});
+    expect(asset.metaData).not.toBe("[object Object]");
+  });
+
+  test("handles metadata object with plain values correctly", () => {
+    const asset = action()
+      .withMetaData({
+        role: "primary",
+        size: "large",
+      })
+      .build({ parentId: "view-1" });
+
+    expect(asset.metaData).toEqual({
+      role: "primary",
+      size: "large",
+    });
+    expect(asset.metaData).not.toBe("[object Object]");
+  });
+
+  test("deeply nested structures with TaggedTemplateValue", () => {
+    const asset = action()
+      .withAdditionalProperties({
+        config: {
+          validation: {
+            rules: [
+              e`conditional(isEmpty({{forms.field1}}), 'required', 'valid')`,
+              e`conditional(isEmpty({{forms.field2}}), 'required', 'valid')`,
+            ],
+            messages: {
+              error: b`forms.errorMessage`,
+              warning: "Please check your input",
+            },
+          },
+        },
+      })
+      .build({ parentId: "view-1" });
+
+    const config = asset.config as {
+      validation: {
+        rules: string[];
+        messages: { error: string; warning: string };
+      };
+    };
+
+    // Check deeply nested arrays with expression syntax
+    expect(Array.isArray(config.validation.rules)).toBe(true);
+    expect(config.validation.rules).toHaveLength(2);
+    expect(config.validation.rules[0]).toBe(
+      "@[conditional(isEmpty({{forms.field1}}), 'required', 'valid')]@",
+    );
+
+    // Check deeply nested objects with binding syntax
+    expect(config.validation.messages).toEqual({
+      error: "{{forms.errorMessage}}",
+      warning: "Please check your input",
+    });
+    expect(config.validation.messages).not.toBe("[object Object]");
+  });
+});

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;
+}