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

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,118 @@
+import { Asset, Flow, DataModel, Navigation, Schema } from "@player-ui/types";
+import { BaseBuildContext, BranchTypes } 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 } from './assets';
+ *
+ * const myFlow = flow({
+ *   id: 'example-flow',
+ *   views: [text().withValue('Some Text').withId('view-1')],
+ *   navigation: {
+ *     BEGIN: 'FLOW_1',
+ *     FLOW_1: {
+ *       startState: 'VIEW_1',
+ *       VIEW_1: { state_type: 'VIEW', ref: 'view-1', transitions: { '*': 'END_Done' } },
+ *       END_Done: { state_type: 'END', outcome: 'done' }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+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: BranchTypes.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;
+    };
+
+    return processViews();
+  })();
+
+  // Extract core properties that need special handling (views and context are handled separately)
+  const { views: _views, context: _context, ...restOptions } = options;
+  void _views; // Handled via processedViews
+  void _context; // Used to construct view build context
+
+  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";

package/src/core/mocks/generated/action.builder.ts

@@ -0,0 +1,92 @@
+import type { ActionAsset, ActionMetaData } from "../types/action.js";
+import type { Asset } from "@player-ui/types";
+import { type FluentBuilder, type BaseBuildContext, type FluentPartial, FluentBuilderBase, createInspectMethod, type TaggedTemplateValue } from "../../../gen/common.js";
+
+export interface ActionAssetBuilderMethods<AnyAsset extends Asset = Asset> {
+  /** A unique identifier for this asset */
+  withId(value: string | TaggedTemplateValue<string>): ActionAssetBuilder<AnyAsset>;
+  /** The transition value of the action in the state machine */
+  withValue(value: string | TaggedTemplateValue<string>): ActionAssetBuilder<AnyAsset>;
+  /** A text-like asset for the action's label */
+  withLabel(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ActionAssetBuilder<AnyAsset>;
+  /** An optional expression to execute before transitioning */
+  withExp(value: string | TaggedTemplateValue<string>): ActionAssetBuilder<AnyAsset>;
+  /** An optional string that describes the action for screen-readers */
+  withAccessibility(value: string | TaggedTemplateValue<string>): ActionAssetBuilder<AnyAsset>;
+  /** An optional confirmation dialog to show before executing the action */
+  withConfirmation(value: { message: string | TaggedTemplateValue<string>; affirmativeLabel: string | TaggedTemplateValue<string>; negativeLabel?: string | TaggedTemplateValue<string> } | FluentBuilder<{ message: string | TaggedTemplateValue<string>; affirmativeLabel: string | TaggedTemplateValue<string>; negativeLabel?: string | TaggedTemplateValue<string> }, BaseBuildContext> | FluentPartial<{ message: string | TaggedTemplateValue<string>; affirmativeLabel: string | TaggedTemplateValue<string>; negativeLabel?: string | TaggedTemplateValue<string> }, BaseBuildContext>): ActionAssetBuilder<AnyAsset>;
+  /** Additional optional data to assist with the action interactions on the page */
+  withMetaData(value: ActionMetaData | FluentBuilder<ActionMetaData, BaseBuildContext> | FluentPartial<ActionMetaData, BaseBuildContext>): ActionAssetBuilder<AnyAsset>;
+  /** Triggers the listed bindings to be validated */
+  withValidate(value: Array<string | TaggedTemplateValue<string>> | string | TaggedTemplateValue<string>): ActionAssetBuilder<AnyAsset>;
+}
+
+/**
+ * A builder for ActionAsset
+ */
+export class ActionAssetBuilder<AnyAsset extends Asset = Asset> extends FluentBuilderBase<ActionAsset<AnyAsset>> implements ActionAssetBuilderMethods<AnyAsset>, FluentBuilder<ActionAsset<AnyAsset>, BaseBuildContext> {
+  private static readonly defaults: Record<string, unknown> = {"type":"action","id":""};
+  private static readonly __arrayProperties__: ReadonlySet<string> = new Set(["validate"]);
+  private static readonly __assetWrapperPaths__: ReadonlyArray<ReadonlyArray<string>> = [["label"]];
+
+  /** A unique identifier for this asset */
+  withId(value: string | TaggedTemplateValue<string>): ActionAssetBuilder<AnyAsset> {
+    return this.set("id", value);
+  }
+
+  /** The transition value of the action in the state machine */
+  withValue(value: string | TaggedTemplateValue<string>): ActionAssetBuilder<AnyAsset> {
+    return this.set("value", value);
+  }
+
+  /** A text-like asset for the action's label */
+  withLabel(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ActionAssetBuilder<AnyAsset> {
+    return this.set("label", value);
+  }
+
+  /** An optional expression to execute before transitioning */
+  withExp(value: string | TaggedTemplateValue<string>): ActionAssetBuilder<AnyAsset> {
+    return this.set("exp", value);
+  }
+
+  /** An optional string that describes the action for screen-readers */
+  withAccessibility(value: string | TaggedTemplateValue<string>): ActionAssetBuilder<AnyAsset> {
+    return this.set("accessibility", value);
+  }
+
+  /** An optional confirmation dialog to show before executing the action */
+  withConfirmation(value: { message: string | TaggedTemplateValue<string>; affirmativeLabel: string | TaggedTemplateValue<string>; negativeLabel?: string | TaggedTemplateValue<string> } | FluentBuilder<{ message: string | TaggedTemplateValue<string>; affirmativeLabel: string | TaggedTemplateValue<string>; negativeLabel?: string | TaggedTemplateValue<string> }, BaseBuildContext> | FluentPartial<{ message: string | TaggedTemplateValue<string>; affirmativeLabel: string | TaggedTemplateValue<string>; negativeLabel?: string | TaggedTemplateValue<string> }, BaseBuildContext>): ActionAssetBuilder<AnyAsset> {
+    return this.set("confirmation", value);
+  }
+
+  /** Additional optional data to assist with the action interactions on the page */
+  withMetaData(value: ActionMetaData | FluentBuilder<ActionMetaData, BaseBuildContext> | FluentPartial<ActionMetaData, BaseBuildContext>): ActionAssetBuilder<AnyAsset> {
+    return this.set("metaData", value);
+  }
+
+  /** Triggers the listed bindings to be validated */
+  withValidate(value: Array<string | TaggedTemplateValue<string>> | string | TaggedTemplateValue<string>): ActionAssetBuilder<AnyAsset> {
+    return this.set("validate", value);
+  }
+
+  /**
+   * Builds the final ActionAsset object
+   * @param context - Optional build context for nested builders
+   */
+  build(context?: BaseBuildContext): ActionAsset<AnyAsset> {
+    return this.buildWithDefaults(ActionAssetBuilder.defaults, context);
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return createInspectMethod("ActionAssetBuilder", this.values);
+  }
+}
+
+/**
+ * Creates a new ActionAsset builder
+ * @param initial Optional initial values
+ * @returns A fluent builder for ActionAsset
+ */
+export function action<AnyAsset extends Asset = Asset>(initial?: FluentPartial<ActionAsset<AnyAsset>>): ActionAssetBuilder<AnyAsset> {
+  return new ActionAssetBuilder<AnyAsset>(initial);
+}

package/src/core/mocks/generated/choice-item.builder.ts

@@ -0,0 +1,120 @@
+import type { ChoiceItem, ChoiceInputModifier, ChoiceItemMetadata } from "../types/choice.js";
+import type { Asset } from "@player-ui/types";
+import { type FluentBuilder, type BaseBuildContext, type FluentPartial, FluentBuilderBase, createInspectMethod, type TaggedTemplateValue } from "../../../gen/common.js";
+
+export interface ChoiceItemBuilderMethods<AnyAsset extends Asset = Asset> {
+  /** The id associated with the choice item */
+  withId(value: string | TaggedTemplateValue<string>): ChoiceItemBuilder<AnyAsset>;
+  /** The id used for replay tests. */
+  withAutomationId(value: string | TaggedTemplateValue<string>): ChoiceItemBuilder<AnyAsset>;
+  /** The label describing the choice. */
+  withLabel(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset>;
+  /** The icon describing the choice. */
+  withIcon(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset>;
+  /** The help for the choice. */
+  withHelp(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset>;
+  /** Support the legacy choiceHelp prop. No storybook docs for this; deprecated in favour of the "help" field. */
+  withChoiceHelp(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset>;
+  /** The description of the choice. */
+  withDescription(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset>;
+  /** The footer of the choice. */
+  withFooter(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset>;
+  /** The value to set when this choice is selected */
+  withValue(value: string | TaggedTemplateValue<string> | number | TaggedTemplateValue<number> | boolean | TaggedTemplateValue<boolean> | null): ChoiceItemBuilder<AnyAsset>;
+  /** The details shown when a user selects the choice item */
+  withChoiceDetail(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset>;
+  /** Any modifiers for the current item. No storybook docs for this as "readonly" (the only modifier) shouldn't be used anymore. */
+  withModifiers(value: Array<ChoiceInputModifier | FluentBuilder<ChoiceInputModifier, BaseBuildContext> | FluentPartial<ChoiceInputModifier, BaseBuildContext>>): ChoiceItemBuilder<AnyAsset>;
+  /** MetaData for the choiceItem */
+  withMetaData(value: ChoiceItemMetadata | FluentBuilder<ChoiceItemMetadata, BaseBuildContext> | FluentPartial<ChoiceItemMetadata, BaseBuildContext>): ChoiceItemBuilder<AnyAsset>;
+}
+
+/**
+ * A builder for ChoiceItem
+ */
+export class ChoiceItemBuilder<AnyAsset extends Asset = Asset> extends FluentBuilderBase<ChoiceItem<AnyAsset>> implements ChoiceItemBuilderMethods<AnyAsset>, FluentBuilder<ChoiceItem<AnyAsset>, BaseBuildContext> {
+  private static readonly defaults: Record<string, unknown> = {"id":""};
+  private static readonly __arrayProperties__: ReadonlySet<string> = new Set(["modifiers"]);
+  private static readonly __assetWrapperPaths__: ReadonlyArray<ReadonlyArray<string>> = [["label"],["icon"],["help"],["choiceHelp"],["description"],["footer"],["choiceDetail"]];
+
+  /** The id associated with the choice item */
+  withId(value: string | TaggedTemplateValue<string>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("id", value);
+  }
+
+  /** The id used for replay tests. */
+  withAutomationId(value: string | TaggedTemplateValue<string>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("automationId", value);
+  }
+
+  /** The label describing the choice. */
+  withLabel(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("label", value);
+  }
+
+  /** The icon describing the choice. */
+  withIcon(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("icon", value);
+  }
+
+  /** The help for the choice. */
+  withHelp(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("help", value);
+  }
+
+  /** Support the legacy choiceHelp prop. No storybook docs for this; deprecated in favour of the "help" field. */
+  withChoiceHelp(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("choiceHelp", value);
+  }
+
+  /** The description of the choice. */
+  withDescription(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("description", value);
+  }
+
+  /** The footer of the choice. */
+  withFooter(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("footer", value);
+  }
+
+  /** The value to set when this choice is selected */
+  withValue(value: string | TaggedTemplateValue<string> | number | TaggedTemplateValue<number> | boolean | TaggedTemplateValue<boolean> | null): ChoiceItemBuilder<AnyAsset> {
+    return this.set("value", value);
+  }
+
+  /** The details shown when a user selects the choice item */
+  withChoiceDetail(value: Asset | FluentBuilder<Asset, BaseBuildContext>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("choiceDetail", value);
+  }
+
+  /** Any modifiers for the current item. No storybook docs for this as "readonly" (the only modifier) shouldn't be used anymore. */
+  withModifiers(value: Array<ChoiceInputModifier | FluentBuilder<ChoiceInputModifier, BaseBuildContext> | FluentPartial<ChoiceInputModifier, BaseBuildContext>>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("modifiers", value);
+  }
+
+  /** MetaData for the choiceItem */
+  withMetaData(value: ChoiceItemMetadata | FluentBuilder<ChoiceItemMetadata, BaseBuildContext> | FluentPartial<ChoiceItemMetadata, BaseBuildContext>): ChoiceItemBuilder<AnyAsset> {
+    return this.set("metaData", value);
+  }
+
+  /**
+   * Builds the final ChoiceItem object
+   * @param context - Optional build context for nested builders
+   */
+  build(context?: BaseBuildContext): ChoiceItem<AnyAsset> {
+    return this.buildWithDefaults(ChoiceItemBuilder.defaults, context);
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return createInspectMethod("ChoiceItemBuilder", this.values);
+  }
+}
+
+/**
+ * Creates a new ChoiceItem builder
+ * @param initial Optional initial values
+ * @returns A fluent builder for ChoiceItem
+ */
+export function choiceItem<AnyAsset extends Asset = Asset>(initial?: FluentPartial<ChoiceItem<AnyAsset>>): ChoiceItemBuilder<AnyAsset> {
+  return new ChoiceItemBuilder<AnyAsset>(initial);
+}