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

package/src/core/tagged-template/types.ts

@@ -0,0 +1,123 @@
+import type { Schema } from "@player-ui/types";
+
+export const TaggedTemplateValueSymbol: unique symbol = Symbol(
+  "TaggedTemplateValue",
+);
+
+export interface TemplateRefOptions {
+  nestedContext?: "binding" | "expression";
+}
+
+export interface TaggedTemplateValue<T = unknown> {
+  [TaggedTemplateValueSymbol]: true;
+  /** Phantom type marker - not available at runtime */
+  readonly _phantomType?: T;
+  toValue(): string;
+  toRefString(options?: TemplateRefOptions): string;
+  toString(): string;
+}
+
+export function isTaggedTemplateValue(
+  value: unknown,
+): value is TaggedTemplateValue {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    TaggedTemplateValueSymbol in value
+  );
+}
+
+/**
+ * Type that converts an object type to a bindable proxy type
+ * Each property access returns a TaggedTemplateValue with the correct type
+ */
+export type BindableProxy<T> = {
+  readonly [K in keyof T]: T[K] extends unknown[]
+    ? TaggedTemplateValue<T[K]> // Arrays become bindings directly
+    : T[K] extends object
+      ? BindableProxy<T[K]> // Objects become nested proxies
+      : TaggedTemplateValue<T[K]>; // Primitives become bindings
+};
+
+/**
+ * Maps primitive Schema types to their corresponding TypeScript types
+ */
+type PrimitiveTypeMap = {
+  StringType: string;
+  NumberType: number;
+  BooleanType: boolean;
+};
+
+/**
+ * Utility to force TypeScript to fully evaluate a type
+ */
+type Evaluate<T> = T extends infer U ? { [K in keyof U]: U[K] } : never;
+
+/**
+ * Check if a type name is primitive
+ */
+type IsPrimitiveType<T extends string> = T extends keyof PrimitiveTypeMap
+  ? true
+  : false;
+
+/**
+ * Convert a primitive type name to its TaggedTemplateValue
+ */
+type PrimitiveToBinding<T extends string> = T extends keyof PrimitiveTypeMap
+  ? TaggedTemplateValue<PrimitiveTypeMap[T]>
+  : TaggedTemplateValue<string>;
+
+/**
+ * Process a single field from a node into its binding representation
+ */
+type ProcessField<
+  Field extends Schema.DataTypes,
+  S extends Schema.Schema,
+  CurrentPath extends string,
+> = Field extends { type: infer TypeName extends string }
+  ? Field extends { isArray: true }
+    ? // Handle array fields
+      IsPrimitiveType<TypeName> extends true
+      ? TypeName extends "StringType"
+        ? { name: PrimitiveToBinding<TypeName> }
+        : { value: PrimitiveToBinding<TypeName> }
+      : TypeName extends keyof S
+        ? S[TypeName] extends Schema.Node
+          ? ProcessNodeFields<S[TypeName], S, `${CurrentPath}._current_`>
+          : TaggedTemplateValue<string>
+        : TaggedTemplateValue<string>
+    : // Handle non-array fields
+      IsPrimitiveType<TypeName> extends true
+      ? PrimitiveToBinding<TypeName>
+      : TypeName extends keyof S
+        ? S[TypeName] extends Schema.Node
+          ? ProcessNodeFields<S[TypeName], S, CurrentPath>
+          : TaggedTemplateValue<string>
+        : TaggedTemplateValue<string>
+  : TaggedTemplateValue<string>;
+
+/**
+ * Process all fields in a node
+ */
+type ProcessNodeFields<
+  Node extends Schema.Node,
+  S extends Schema.Schema,
+  BasePath extends string,
+> = Evaluate<{
+  [K in keyof Node]: ProcessField<
+    Node[K],
+    S,
+    BasePath extends "" ? K & string : `${BasePath}.${K & string}`
+  >;
+}>;
+
+/**
+ * Main type to extract bindings from a schema
+ */
+export type ExtractedBindings<S extends Schema.Schema> = S extends {
+  ROOT: infer RootNode;
+}
+  ? RootNode extends Schema.Node
+    ? ProcessNodeFields<RootNode, S, "">
+    : never
+  : never;

package/src/core/template/__tests__/index.test.ts

@@ -0,0 +1,380 @@
+import { describe, test, expect, beforeEach } from "vitest";
+import type { Template, Asset } from "@player-ui/types";
+import { template, isTemplate, TEMPLATE_MARKER } from "../index";
+import {
+  type BaseBuildContext,
+  type SlotBranch,
+  resetGlobalIdSet,
+} from "../../base-builder";
+import { text } from "../../mocks";
+import { binding as b } from "../../tagged-template";
+
+// Mock BaseBuildContext
+const mockBaseBuildContext: BaseBuildContext = {
+  parentId: "parent-1",
+  branch: {
+    type: "slot",
+    name: "test",
+  } as SlotBranch,
+};
+
+describe("template", () => {
+  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_`),
+    })(mockBaseBuildContext);
+
+    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_`),
+    })(mockBaseBuildContext);
+
+    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_`),
+    })(mockBaseBuildContext);
+
+    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_`),
+    })(mockBaseBuildContext);
+
+    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 capturedBaseBuildContext: BaseBuildContext | null = null;
+
+    const valueWithCapture = (parentCtx: BaseBuildContext): Asset<"text"> => {
+      capturedBaseBuildContext = parentCtx;
+      return {
+        id: "test",
+        type: "text",
+        value: "test",
+      };
+    };
+
+    template({
+      data: "list.of.names",
+      output: "values",
+      value: valueWithCapture,
+    })(mockBaseBuildContext);
+
+    expect(capturedBaseBuildContext).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_`),
+    })(mockBaseBuildContext);
+
+    const template2 = template({
+      data: "list.of.other-names",
+      output: "values",
+      value: text().withValue(b`list.of.other-names._index_`),
+    })(mockBaseBuildContext);
+
+    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,
+    })(mockBaseBuildContext);
+
+    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_`),
+    })(mockBaseBuildContext);
+
+    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(mockBaseBuildContext);
+
+    // 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");
+  });
+});

package/src/core/template/index.ts

@@ -0,0 +1,196 @@
+import type { Asset, Template } from "@player-ui/types";
+import {
+  type BaseBuildContext,
+  genId,
+  isFluentBuilder,
+  BranchTypes,
+} from "../base-builder";
+import {
+  isTaggedTemplateValue,
+  type TaggedTemplateValue,
+} from "../tagged-template";
+
+/**
+ * Symbol marker to identify template functions
+ */
+export const TEMPLATE_MARKER = Symbol.for("fluent-builder-template");
+
+/**
+ * Type guard to check if a function is a template function
+ */
+export function isTemplate(fn: unknown): fn is ReturnType<typeof template> {
+  return (
+    typeof fn === "function" &&
+    TEMPLATE_MARKER in (fn as { [TEMPLATE_MARKER]?: unknown })
+  );
+}
+
+/**
+ * Arguments for creating a template configuration
+ * @template T - The type of asset that will be created for each item in the array
+ */
+interface TemplateArgs<T extends Asset<string>> {
+  /** A binding that points to an array in the model */
+  readonly data: string | TaggedTemplateValue;
+  /** A property to put the mapped objects. If not provided, will be inferred from context */
+  readonly output?: string;
+  /** The asset creator - can be a static asset, a FluentBuilder, or a builder function that returns an asset */
+  readonly value:
+    | T
+    | { build(context?: BaseBuildContext): T }
+    | (<K extends BaseBuildContext>(ctx: K) => T);
+  /** Whether template should be recomputed when data changes */
+  readonly dynamic?: boolean;
+}
+
+/**
+ * Creates a template configuration for dynamically creating a list of assets based on array data.
+ * Templates provide a way to dynamically create a list of assets, or any object, based on data from the model.
+ * All of the templating semantics are removed by the time it reaches an asset's transform or UI layer.
+ *
+ * Within a template, the `_index_` string can be used to substitute the array-index of the item being mapped.
+ *
+ * Multiple templates:
+ * - Templates can be nested. Use `_index_` for the outer loop, `_index1_` for the inner loop, and so on.
+ * - Multiple templates can output to the same property using the same output name. Items will be appended.
+ * - Templates can append to existing arrays by using the same output property name.
+ *
+ * Dynamic vs Static Templates:
+ * - If dynamic is false (default), the template will be parsed when a view first renders and won't update as data changes.
+ * - If dynamic is true, template will be updated whenever data changes while a view is still showing.
+ *
+ * @param args - The template configuration arguments
+ * @returns A function that takes parent context and returns a Template configuration
+ * @see https://player-ui.github.io/next/content/assets-views/#templates
+ * @example
+ * ```ts
+ * // Using a static asset
+ * template({
+ *   data: binding`users`,
+ *   output: "items",
+ *   value: text({ value: binding`users._index_.name` })
+ * })(parentCtx)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Using a builder function
+ * template({
+ *   data: binding`users`,
+ *   output: "items",
+ *   value: (ctx) => text({ value: binding`users._index_.name` }).withId(genId(ctx))
+ * })(parentCtx)
+ * ```
+ *
+ * @example Multiple templates with the same output
+ * ```ts
+ * [
+ *   template({
+ *     data: binding`names`,
+ *     output: "values",
+ *     value: text({ id: `name-_index_`, value: binding`names._index_` })
+ *   })(parentCtx),
+ *   template({
+ *     data: binding`otherNames`,
+ *     output: "values",
+ *     value: text({ id: `other-name-_index_`, value: binding`otherNames._index_` })
+ *   })(parentCtx)
+ * ]
+ * ```
+ *
+ * @example Dynamic template that updates when data changes
+ * ```ts
+ * template({
+ *   data: binding`users`,
+ *   output: "items",
+ *   dynamic: true,
+ *   value: text({ value: binding`users._index_.name` })
+ * })(parentCtx)
+ * ```
+ */
+export const template = <T extends Asset<string>>({
+  data,
+  output,
+  value,
+  dynamic = false,
+}: TemplateArgs<T>) => {
+  const templateFn = (parentCtx: BaseBuildContext): Template<{ asset: T }> => {
+    // If output is not provided, try to infer from context
+    const resolvedOutput = output || inferOutputFromContext(parentCtx);
+
+    if (!resolvedOutput) {
+      throw new Error(
+        "Template output must be provided or inferrable from context. " +
+          "When using template in asset arrays, ensure the array property can be inferred " +
+          "(e.g., collection().withValues([template(...)]) infers 'values' as output).",
+      );
+    }
+
+    // Create template context for the value - use the generated parent ID to include slot context
+    const templateValueCtx: BaseBuildContext = {
+      parentId: genId(parentCtx),
+      branch: {
+        type: BranchTypes.TEMPLATE,
+        depth: 0,
+      },
+    };
+
+    let resolvedAsset: T;
+    if (isFluentBuilder(value)) {
+      resolvedAsset = value.build(templateValueCtx) as T;
+    } else if (typeof value === "function") {
+      const builderResult = value(templateValueCtx);
+      if (typeof builderResult === "function") {
+        resolvedAsset = (builderResult as (ctx: BaseBuildContext) => T)(
+          templateValueCtx,
+        );
+      } else {
+        resolvedAsset = builderResult;
+      }
+    } else {
+      if (typeof value === "object" && value !== null) {
+        resolvedAsset = { ...value } as T;
+      } else {
+        resolvedAsset = value;
+      }
+    }
+
+    return {
+      data: isTaggedTemplateValue(data) ? data.toString() : data,
+      output: resolvedOutput,
+      value: {
+        asset: resolvedAsset,
+      },
+      ...(dynamic && { dynamic }),
+    };
+  };
+
+  // Add the marker symbol to the function
+  (templateFn as typeof templateFn & { [TEMPLATE_MARKER]: true })[
+    TEMPLATE_MARKER
+  ] = true;
+
+  return templateFn;
+};
+
+/**
+ * Helper function to infer output property name from BaseBuildContext
+ */
+function inferOutputFromContext(
+  parentCtx: BaseBuildContext,
+): string | undefined {
+  // Check if we're in a slot context that can give us the property name
+  if (parentCtx.branch?.type === "slot") {
+    const slotName = parentCtx.branch.name;
+    // Extract property name from slot names like "values-0", "items-2", etc.
+    const match = slotName.match(/^([a-zA-Z_][a-zA-Z0-9_]*)-\d+$/);
+    if (match) {
+      return match[1];
+    }
+    // If it's just a property name without index, use it directly
+    if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(slotName)) {
+      return slotName;
+    }
+  }
+  return undefined;
+}