Merge branch 'advanced-ui'

Author: Eaglenait

angular.json

@@ -32,6 +32,11 @@
               {
                 "glob": "**/*",
                 "input": "public"
+              },
+              {
+                "glob": "**/*.template.ts",
+                "input": "src/app/advanced-presets/templates",
+                "output": "templates"
               }
             ],
             "styles": [

src/app/advanced-presets/counter.preset.ts

@@ -0,0 +1,164 @@
+import { getElementNamesRecursive, UIAdvancedPresetDefinition, UIAnchor, UIBgFill, UIElement, UIParams } from '../../models/types';
+import { IAdvancedExportGenerator, loadTemplate, replacePlaceholders } from '../services/export/advanced-export.builder';
+
+/**
+ * Export generator for the counter preset.
+ * 
+ * Generates a TypeScript class that wraps a counter widget with automatic increment functionality.
+ * This implementation uses a template file (counter.widget.template.ts) for better maintainability.
+ * The template approach provides:
+ * - Proper TypeScript syntax highlighting and validation in the template file
+ * - Easier testing and iteration on the generated code structure
+ * - Clear separation between template logic and placeholder replacement
+ * - Ability to share common patterns across multiple presets
+ * 
+ * @implements {IAdvancedExportGenerator}
+ * 
+ * @example
+ * ```typescript
+ * // Generated class usage in Battlefield modding:
+ * const counter = new CounterWidget();
+ * const widget = counter.create();  // Creates the UI widget
+ * counter.increment();                 // Increments from 0 to 1
+ * counter.decrement();                 // Increments from 1 to 0
+ * ```
+ */
+export class CounterExportGenerator implements IAdvancedExportGenerator {
+  private templateCache: string | null = null;
+
+  /**
+   * Generates TypeScript class code for a counter widget instance.
+   * 
+   * Loads the counter widget template and replaces placeholders with actual values:
+   * - {{CLASS_NAME}} - Unique class name for this instance
+   * - {{TIMESTAMP}} - Generation timestamp
+   * - {{UI_PARAMS}} - Serialized UI parameters for modlib.ParseUI()
+   * 
+   * The template is cached after first load to avoid repeated network requests.
+   * 
+   * @param rootElement - The root container element of the counter preset
+   * @param preset - The counter preset definition
+   * @param className - Unique class name for this counter instance
+   * @param serializeHelpers - Helper functions for converting UI elements to TypeScript
+   * @param serializeHelpers.serializeParamToTypescript - Converts UIParams to object literal code
+   * @param serializeHelpers.serializeElement - Extracts UIParams from UIElement
+   * @param strings - Localization strings (passed through to serialization)
+   * @param timestamp - ISO timestamp for code generation comment header
+   * @returns Complete TypeScript class definition as a string
+   */
+  async generateClassCode(
+    rootElement: UIElement,
+    preset: UIAdvancedPresetDefinition,
+    className: string,
+    serializeHelpers: {
+      serializeParamToTypescript: (param: UIParams, indentLevel: number, strings: Record<string, string>) => string;
+      serializeElement: (e: UIElement) => UIParams;
+    },
+    strings: Record<string, string>,
+    timestamp: string
+  ): Promise<string> {
+    const { serializeParamToTypescript, serializeElement } = serializeHelpers;
+    
+    // Load template (cached after first load)
+    if (!this.templateCache) {
+      this.templateCache = await loadTemplate('counter.widget.template.ts');
+    }
+
+    // Serialize the root element into TypeScript object literal format
+    const params = serializeElement(rootElement);
+    const uiParams = serializeParamToTypescript(params, 3, strings);
+
+    // Replace placeholders in template
+    return replacePlaceholders(this.templateCache, {
+      CLASS_NAME: className,
+      TIMESTAMP: timestamp,
+      UI_PARAMS: uiParams
+    });
+  }
+}
+
+/**
+ * Unique identifier for the counter preset.
+ * Used to register and look up this preset in the preset registry.
+ */
+export const COUNTER_PRESET_ID = 'counter-container';
+
+/**
+ * UI element blueprint for the counter preset.
+ * 
+ * Defines the visual structure of the counter widget:
+ * - A semi-transparent dark container (360x140px)
+ * - A centered text element inside for displaying the counter value
+ * 
+ * This blueprint is instantiated when a user adds a counter preset to the canvas.
+ * The actual counter value (0, 1, 2...) is set at runtime via the increment() decrement() methods
+ * in the generated TypeScript class.
+ */
+const blueprint: UIParams = {
+    name: "CounterContainer",
+    type: "Container",
+    position: [49.97, 28.93],
+    size: [210, 210],
+    anchor: UIAnchor.TopLeft,
+    visible: true,
+    padding: 0,
+    bgColor: [0.2, 0.2, 0.2],
+    bgAlpha: 1,
+    bgFill: UIBgFill.Blur,
+    children: [
+      {
+        name: "CounterText",
+        type: "Text",
+        position: [0, 0],
+        size: [150, 150],
+        anchor: UIAnchor.Center,
+        visible: true,
+        padding: 0,
+        bgColor: [0.2, 0.2, 0.2],
+        bgAlpha: 1,
+        bgFill: UIBgFill.None,
+        textLabel: "0",
+        textColor: [1, 1, 1],
+        textAlpha: 1,
+        textSize: 38,
+        textAnchor: UIAnchor.Center
+      }
+    ]
+};
+
+/**
+ * Counter preset definition.
+ * 
+ * Defines a reusable counter widget that can be added to the UI builder canvas.
+ * When exported, generates a TypeScript class with:
+ * - A create() method that instantiates the widget
+ * - A increment() and decrement() method to modify the counter value
+ * - Public properties for accessing the container and text widgets
+ * 
+ * This preset demonstrates the advanced preset system's capabilities:
+ * - Complex multi-element widgets
+ * - Custom export logic via CounterExportGenerator
+ * - Slot definitions for customizable child elements
+ * - Integration with the Battlefield modlib.ParseUI() system
+ * 
+ * @see CounterExportGenerator for the export code generation logic
+ * @see UIAdvancedPresetDefinition for the preset type definition
+ */
+export const counterPreset: UIAdvancedPresetDefinition = {
+  id: COUNTER_PRESET_ID,
+  label: 'Counter Container',
+  version: '1.0.0',
+  description: 'Container with a text widget that be incremented or decremented.',
+  defaultClassName: 'CounterWidget',
+  defaultRootName: 'CounterContainer',
+  blueprint,
+  slots: [
+    {
+      id: 'counterText',
+      label: 'Counter Text',
+      description: 'Text widget displaying the numeric counter.',
+      allowedTypes: ['Text'],
+    },
+  ],
+  exportGenerator: new CounterExportGenerator(),
+};

src/app/advanced-presets/registry.ts

@@ -0,0 +1,58 @@
+import { UiBuilderService } from '../services/ui-builder.service';
+import { counterPreset, COUNTER_PRESET_ID } from './counter.preset';
+
+/**
+ * Registers all built-in advanced presets with the UI builder service.
+ * 
+ * This function is called during service initialization to make all advanced presets
+ * available in the UI builder. To add a new advanced preset:
+ * 
+ * 1. Create a new preset file in this directory (e.g., `my-widget.preset.ts`)
+ * 2. Define the preset definition and export generator class
+ * 3. Import the preset in this file
+ * 4. Call `service.registerAdvancedPreset()` with your preset
+ * 5. Add the preset ID to `getBuiltInPresetIds()` array
+ * 
+ * @param service - The UI builder service instance
+ * 
+ * @example
+ * ```typescript
+ * // Adding a new preset:
+ * import { myPreset, MY_PRESET_ID } from './my-widget.preset';
+ * 
+ * export function registerAllAdvancedPresets(service: UiBuilderService) {
+ *   service.registerAdvancedPreset(counterPreset as any);
+ *   service.registerAdvancedPreset(myPreset as any);  // Add your preset here
+ * }
+ * 
+ * export function getBuiltInPresetIds(): string[] {
+ *   return [COUNTER_PRESET_ID, MY_PRESET_ID];  // Add your preset ID here
+ * }
+ * ```
+ */
+export function registerAllAdvancedPresets(service: UiBuilderService) {
+  // Register built-in presets
+  service.registerAdvancedPreset(counterPreset as any);
+}
+
+/**
+ * Returns an array of all built-in advanced preset IDs.
+ * 
+ * This function provides a centralized list of all preset IDs for validation,
+ * filtering, and management purposes. Update this list whenever adding or
+ * removing built-in presets.
+ * 
+ * @returns Array of preset ID strings
+ * 
+ * @example
+ * ```typescript
+ * const builtInIds = getBuiltInPresetIds();
+ * // Returns: ['counter-container']
+ * 
+ * // Check if a preset is built-in:
+ * const isBuiltIn = getBuiltInPresetIds().includes(presetId);
+ * ```
+ */
+export function getBuiltInPresetIds(): string[] {
+  return [COUNTER_PRESET_ID];
+}

src/app/advanced-presets/templates/README.md

@@ -0,0 +1,46 @@
+# Advanced Preset Templates
+
+This directory contains TypeScript template files for advanced preset export generators.
+
+## Overview
+
+Template files allow you to write the generated TypeScript code in actual `.ts` files that are then correctly serialized when generating UIs.
+
+## How It Works
+
+1. **Template Files**: Write your widget class in a `.template.ts` file using placeholder syntax `{{PLACEHOLDER_NAME}}`
+2. **Build Process**: Template files are excluded from TypeScript compilation but copied as-is to `dist/templates/`
+3. **Runtime Loading**: Export generators use `loadTemplate()` to fetch templates and `replacePlaceholders()` to substitute values
+
+## Available Placeholders
+
+Common placeholders you can use in your templates:
+
+- `{{CLASS_NAME}}` - The unique class name for this widget instance
+- `{{TIMESTAMP}}` - ISO timestamp for generation comment headers
+- `{{UI_PARAMS}}` - Serialized UIParams for `modlib.ParseUI()`
+
+You can define custom placeholders specific to your preset needs.
+
+## Common Interface (Documentation Only)
+
+The `common-interface.ts` file documents the expected interface for all generated widgets:
+- `create()` - Creates and initializes the widget
+- `update()` - Updates widget state
+- `destroy()` - Cleanup (optional)
+
+This file is for reference only and is not compiled or exported.
+It's also expected to expose as public properties the important widget instances for easier manipulation.
+
+## Adding New Templates
+
+1. Create a new `.template.ts` file in this directory
+2. Write your widget class using placeholder syntax
+3. Create an export generator class that loads and uses your template
+4. Register the preset in `registry.ts`
+
+## File Naming Convention
+
+- Use `.template.ts` extension for actual template files
+- Templates will be copied to `dist/templates/` during build
+- Use descriptive names: `[preset-name].widget.template.ts`

src/app/advanced-presets/templates/common-interface.ts

@@ -0,0 +1,38 @@
+//@ts-ignore
+/**
+ * Common interface that all advanced widget classes should implement.
+ * This ensures consistent API across all generated widgets.
+ * 
+ * NOTE: This file is for documentation purposes only. The actual interface
+ * is not enforced at runtime since widgets are generated as standalone classes.
+ * Use this as a reference when creating new widget templates.
+ * 
+ * Ideally if someone generates ui with the tool they can implement this interface manually in exported code and handle widget lifecycle properly.
+ */
+export interface IAdvancedWidget {
+  /**
+   * Useful widget instances should be created and stored in public properties.
+   * We can also, at the end of the create() method, chain `mod.FindUIWidgetWithName(...)` and assign them there.
+   */
+  rootWidget: mod.UIWidget;
+
+  /**
+   * Creates and initializes the widget.
+   * Should call modlib.ParseUI() and set up any widget references.
+   * @returns The root widget instance
+   */
+  create(): mod.UIWidget;
+
+  /**
+   * Updates the widget state and refreshes the display.
+   * The specific behavior depends on the widget type.
+   * @returns Optional return value (e.g., new counter value)
+   */
+  refreshUi?(): any;
+
+  /**
+   * Destroys the widget and cleans up resources.
+   * Should be implemented if the widget needs cleanup.
+   */
+  destroy?(): void;
+}

src/app/advanced-presets/templates/counter.widget.template.ts

@@ -0,0 +1,39 @@
+export class {{CLASS_NAME}} {
+  public containerWidget: mod.UIWidget = null;
+  public textWidget: mod.UIWidget = null;
+
+  private counterValue = 0;
+
+  public create(): mod.UIWidget {
+    this.counterValue = 0;
+    this.containerWidget = modlib.ParseUI(
+{{UI_PARAMS}}
+    );
+    this.textWidget = mod.FindUIWidgetWithName('CounterText');
+    this.refreshUi();
+    return this.containerWidget;
+  }
+
+  public increment(): number {
+    this.counterValue += 1;
+    this.refreshUi();
+    return this.counterValue;
+  }
+
+  public decrement(): number {
+    this.counterValue -= 1;
+    this.refreshUi();
+    return this.counterValue;
+  }
+
+  pulic destroy() {
+    if (this.containerWidget) {
+        mod.DeleteUIWidget(this.containerWidget);
+    }
+  }
+
+  private refreshUi(): void {
+    mod.SetUITextLabel(this.textWidget, mod.Message(this.counterValue.toString()));
+  }
+
+}