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

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

@@ -0,0 +1,184 @@
+import { Asset, AssetWrapper } from "@player-ui/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");
+
+/**
+ * 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> = T extends
+  | AssetWrapper<infer A>
+  | undefined
+  ? // For AssetWrapper properties, allow unwrapped builders/assets
+    | 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>)
+  : // For other properties, just allow the normal types
+    T | FluentBuilder<T, C> | (() => T | FluentBuilder<T, 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,
+  )} }`;
+}

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

@@ -0,0 +1,292 @@
+import { describe, it, expect } from "vitest";
+import { flow } from "..";
+import { Flow } from "@player-ui/types";
+import { text } from "../../mocks";
+
+describe("flow function", () => {
+  it("should create a flow with basic properties", () => {
+    const result = flow({
+      id: "test-flow",
+      topic: "test-flow",
+      views: [text({ value: "Hello World" })],
+      data: {
+        greeting: "Hello",
+      },
+      navigation: {
+        BEGIN: "FLOW_1",
+        FLOW_1: {
+          startState: "VIEW_1",
+          VIEW_1: {
+            state_type: "VIEW",
+            ref: "view-1",
+            transitions: {},
+          },
+        },
+      },
+    });
+
+    const expected: Flow = {
+      data: {
+        greeting: "Hello",
+      },
+      id: "test-flow",
+      topic: "test-flow",
+      navigation: {
+        BEGIN: "FLOW_1",
+        FLOW_1: {
+          VIEW_1: {
+            ref: "view-1",
+            state_type: "VIEW",
+            transitions: {},
+          },
+          startState: "VIEW_1",
+        },
+      },
+      views: [
+        {
+          id: "test-flow-views-0-text",
+          type: "text",
+          value: "Hello World",
+        },
+      ],
+    };
+
+    expect(result).toEqual(expected);
+  });
+
+  it('should use "root" as default flow ID', () => {
+    const result = flow({
+      views: [text({ value: "Hello World" })],
+      navigation: {
+        BEGIN: "FLOW_1",
+        FLOW_1: {
+          startState: "VIEW_1",
+          VIEW_1: {
+            state_type: "VIEW",
+            ref: "view-1",
+            transitions: {},
+          },
+        },
+      },
+    });
+
+    expect(result.id).toEqual("root");
+  });
+
+  it("should generate hierarchical IDs for views", () => {
+    const result = flow({
+      id: "my-flow",
+      views: [text().withValue("First View"), text().withValue("Second View")],
+      navigation: {
+        BEGIN: "FLOW_1",
+        FLOW_1: {
+          startState: "VIEW_1",
+          VIEW_1: {
+            state_type: "VIEW",
+            ref: "view-1",
+            transitions: {},
+          },
+        },
+      },
+    });
+
+    const expected: Flow["views"] = [
+      {
+        id: "my-flow-views-0-text",
+        type: "text",
+        value: "First View",
+      },
+      {
+        id: "my-flow-views-1-text",
+        type: "text",
+        value: "Second View",
+      },
+    ];
+
+    expect(result.views).toEqual(expected);
+  });
+
+  it("should preserve custom IDs in views", () => {
+    const result = flow({
+      id: "custom-flow",
+      views: [
+        text().withId("custom-view-id").withValue("Custom ID View"),
+        text().withValue("Auto ID View"),
+      ],
+      navigation: {
+        BEGIN: "FLOW_1",
+        FLOW_1: {
+          startState: "VIEW_1",
+          VIEW_1: {
+            state_type: "VIEW",
+            ref: "custom-view-id",
+            transitions: {},
+          },
+        },
+      },
+    });
+
+    const expected: Flow["views"] = [
+      {
+        id: "custom-view-id",
+        type: "text",
+        value: "Custom ID View",
+      },
+      {
+        id: "custom-flow-views-1-text",
+        type: "text",
+        value: "Auto ID View",
+      },
+    ];
+
+    expect(result.views).toEqual(expected);
+  });
+
+  it("should handle function-based view generators", () => {
+    const result = flow({
+      id: "functional-flow",
+      views: [
+        (ctx) => ({
+          id: ctx.parentId ?? "default-id",
+          type: "text" as const,
+          value: "Function Generated View",
+        }),
+      ],
+      navigation: {
+        BEGIN: "FLOW_1",
+        FLOW_1: {
+          startState: "VIEW_1",
+          VIEW_1: {
+            state_type: "VIEW",
+            ref: "view-func",
+            transitions: {},
+          },
+        },
+      },
+    });
+
+    const expected: Flow["views"] = [
+      {
+        id: "functional-flow-views",
+        type: "text",
+        value: "Function Generated View",
+      },
+    ];
+
+    expect(result.views).toEqual(expected);
+  });
+
+  it("should handle a complex flow with multiple properties", () => {
+    const result = flow({
+      id: "complex-flow",
+      views: [
+        text().withId("view-1").withValue("First View"),
+        text().withId("view-2").withValue("Second View"),
+      ],
+      data: {
+        user: {
+          name: "John Doe",
+          email: "john@example.com",
+        },
+        settings: {
+          theme: "dark",
+        },
+      },
+      schema: {
+        ROOT: {
+          user: {
+            type: "object",
+          },
+          settings: {
+            type: "object",
+          },
+        },
+      },
+      navigation: {
+        BEGIN: "MAIN_FLOW",
+        MAIN_FLOW: {
+          startState: "FIRST_VIEW",
+          FIRST_VIEW: {
+            state_type: "VIEW",
+            ref: "view-1",
+            transitions: {
+              NEXT: "SECOND_VIEW",
+            },
+          },
+          SECOND_VIEW: {
+            state_type: "VIEW",
+            ref: "view-2",
+            transitions: {
+              DONE: "END_STATE",
+            },
+          },
+          END_STATE: {
+            state_type: "END",
+            outcome: "completed",
+          },
+        },
+      },
+    });
+
+    const expected: Flow = {
+      data: {
+        settings: {
+          theme: "dark",
+        },
+        user: {
+          email: "john@example.com",
+          name: "John Doe",
+        },
+      },
+      id: "complex-flow",
+      navigation: {
+        BEGIN: "MAIN_FLOW",
+        MAIN_FLOW: {
+          END_STATE: {
+            outcome: "completed",
+            state_type: "END",
+          },
+          FIRST_VIEW: {
+            ref: "view-1",
+            state_type: "VIEW",
+            transitions: {
+              NEXT: "SECOND_VIEW",
+            },
+          },
+          SECOND_VIEW: {
+            ref: "view-2",
+            state_type: "VIEW",
+            transitions: {
+              DONE: "END_STATE",
+            },
+          },
+          startState: "FIRST_VIEW",
+        },
+      },
+      schema: {
+        ROOT: {
+          settings: {
+            type: "object",
+          },
+          user: {
+            type: "object",
+          },
+        },
+      },
+      views: [
+        {
+          id: "view-1",
+          type: "text",
+          value: "First View",
+        },
+        {
+          id: "view-2",
+          type: "text",
+          value: "Second View",
+        },
+      ],
+    };
+
+    expect(result).toEqual(expected);
+  });
+});

package/src/core/flow/index.ts

@@ -0,0 +1,141 @@
+import { Asset, Flow, DataModel, Navigation, Schema } from "@player-ui/types";
+import { BaseBuildContext } from "../base-builder";
+
+/**
+ * Core options for creating a Player-UI Flow
+ */
+interface CoreFlowOptions<
+  T extends Asset = Asset,
+  C extends BaseBuildContext = BaseBuildContext,
+> {
+  id?: string;
+  views: Array<T | { build(context?: C): T } | ((ctx: C) => T)>;
+  data?: DataModel;
+  schema?: Schema.Schema;
+  navigation: Navigation;
+  context?: C;
+}
+
+/**
+ * Options for creating a Player-UI Flow
+ * Allows additional properties to be passed through to the final Flow
+ */
+export type FlowOptions<
+  T extends Asset = Asset,
+  C extends BaseBuildContext = BaseBuildContext,
+> = CoreFlowOptions<T, C> &
+  Omit<Flow<T>, keyof CoreFlowOptions<T, C> | "views">;
+
+/**
+ * Creates a Player-UI Flow from the given options
+ *
+ * @example
+ * ```ts
+ * import { flow } from './flow';
+ * import { text, autogenText } from './assets';
+ *
+ * // Basic usage (no autogen)
+ * const basicFlow = flow({
+ *   id: 'example-flow',
+ *   views: [text('Some Text').binding('label').id('view-1')],
+ *   navigation: { ... }
+ * });
+ *
+ * // Recommended autogen usage
+ * const autogenFlow = flow({
+ *   id: 'autogen-flow',
+ *   autogenRunner: runner,
+ *   autogenInputData: inputData, // Rich NLS data, title, subtitle, etc.
+ *   views: [autogenText({ type: 'header' })],
+ *   navigation: { ... }
+ * });
+ *
+ * // Advanced autogen usage (full control)
+ * const advancedFlow = flow({
+ *   id: 'advanced-flow',
+ *   autogenRunner: runner,
+ *   autogenContext: customContext,
+ *   views: [autogenText({ type: 'header' })],
+ *   navigation: { ... }
+ * });
+ * ```
+ */
+function isBuilder<T>(
+  value: T | { build(context?: BaseBuildContext): T },
+): value is { build(context?: BaseBuildContext): T } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "build" in value &&
+    typeof value.build === "function"
+  );
+}
+
+function isBuilderFunction<T>(
+  value: T | ((ctx: BaseBuildContext) => T),
+): value is (ctx: BaseBuildContext) => T {
+  return typeof value === "function";
+}
+
+export function flow<T extends Asset = Asset>(
+  options: FlowOptions<T>,
+): Flow<T> {
+  const flowId = options.id || "root";
+
+  const viewsNamespace = `${flowId}-views`;
+
+  const processedViews = (() => {
+    const processViews = (): T[] => {
+      const results: T[] = [];
+
+      for (let index = 0; index < options.views.length; index++) {
+        const viewOrFn = options.views[index];
+        const ctx: BaseBuildContext = {
+          parentId: viewsNamespace,
+          branch: {
+            type: "array-item",
+            index,
+          },
+          ...(options.context ?? {}),
+        };
+
+        if (isBuilder(viewOrFn)) {
+          results.push(viewOrFn.build(ctx));
+        } else if (isBuilderFunction(viewOrFn)) {
+          results.push(viewOrFn(ctx));
+        } else {
+          results.push(viewOrFn);
+        }
+      }
+
+      return results;
+    };
+
+    // No autogen runner, process views normally
+    return processViews();
+  })();
+
+  // Extract core properties that need special handling
+  const {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    views: _views,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    context: _context,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    autogenRunner: _autogenRunner,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    autogenInputData: _autogenInputData,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    autogenContext: _autogenContext,
+    ...restOptions
+  } = options;
+
+  return {
+    ...restOptions,
+    id: flowId,
+    views: processedViews,
+    ...(options.data && { data: options.data }),
+    ...(options.schema && { schema: options.schema }),
+    navigation: options.navigation,
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,8 @@
+// Core utilities - building blocks for DSL generation
+export * from "./base-builder";
+export * from "./tagged-template";
+export * from "./template";
+export * from "./switch";
+export * from "./flow";
+export * from "./schema";
+export * from "./utils";