@minecraft/creator-tools/lib/dataform/DataFormUtilities.d.ts

Minecraft Creator Tools command line and libraries.

import IField, { FieldDataType } from "./IField";
import IFormDefinition from "./IFormDefinition";
import ISummarizer, { ISummarizerOptions, ISummarizerResult } from "./ISummarizer";
export default class DataFormUtilities {
    static generateDefaultItem(formDefinition: IFormDefinition): any;
    /**
     * Returns true if the component data only contains default or empty values
     * relative to the form definition — meaning it can be safely removed from
     * the persisted JSON without losing any user intent.
     */
    static isDefaultOrEmpty(formDefinition: IFormDefinition, data: unknown): boolean;
    static selectSubForm(form: IFormDefinition, select: string): IFormDefinition;
    static mergeFields(form: IFormDefinition): void;
    /**
     * Selects the most appropriate field definition (primary or alternate) based on the actual value type.
     *
     * This is the UI-layer component of the "upscale/downscale" pattern. It ensures that
     * when rendering a form, the correct editor is used for the actual data type.
     *
     * BACKGROUND:
     *   Minecraft JSON often supports multiple representations of the same field:
     *   - A scalar: "hello"
     *   - An array: ["a", "b"]
     *   - An object: { items: ["a"], amount: 5 }
     *
     *   Field definitions can have "alternates" - additional field definitions that
     *   represent the same logical field but with different dataTypes and potentially
     *   different subForms.
     *
     * HOW IT WORKS:
     *   1. Collects all field variants (primary + alternates)
     *   2. Scores each variant based on how well its dataType matches the value
     *   3. Returns the highest-scoring variant
     *
     * SCORING RULES:
     *   - Array values prefer stringArray, numberArray, objectArray types
     *   - Object values prefer object types, especially with subForms
     *   - Scalar values prefer matching primitive types (string, int, boolean)
     *
     * USAGE IN DataForm.tsx:
     *   const effectiveField = DataFormUtilities.selectFieldForValue(field, curVal);
     *   // effectiveField is now the variant that best represents curVal
     *   // Use effectiveField.dataType, effectiveField.subForm, etc.
     *
     * RELATED:
     *   - FormPropertyManager.upscaleDirectObject() - Data-layer scalar→object
     *   - FormPropertyManager.downscaleDirectObject() - Data-layer object→scalar
     *
     * @param field - The primary field definition (may have alternates)
     * @param value - The actual value to match against
     * @returns The best-matching field definition (primary or an alternate)
     */
    static selectFieldForValue(field: IField, value: any): IField;
    static isObjectFieldType(fieldDataType: FieldDataType): fieldDataType is FieldDataType.object | FieldDataType.minecraftFilter | FieldDataType.minecraftEventTrigger;
    static isScalarFieldType(fieldDataType: FieldDataType): fieldDataType is FieldDataType.int | FieldDataType.boolean | FieldDataType.string | FieldDataType.float | FieldDataType.intEnum | FieldDataType.intBoolean | FieldDataType.molang;
    static sortFieldsBySignificance(fieldA: IField, fieldB: IField): number;
    static sortFieldsByPriority(fieldA: IField, fieldB: IField): number;
    static loadSubForms(form: IFormDefinition, loadedForms?: string | undefined): Promise<string | undefined>;
    static sortAndCleanAlternateFields(form: IFormDefinition): void;
    static fixupFields(form: IFormDefinition, parentField?: IField): void;
    static generateFormFromObject(id: string, obj: object, exampleSourcePath?: string): {
        id: string;
        title: string;
        fields: IField[];
    };
    static getFieldAndAlternates(fieldDefinition: IField): IField[];
    static getScalarField(formDefinition: IFormDefinition): IField;
    static isString(fieldType: FieldDataType): fieldType is FieldDataType.string | FieldDataType.stringEnum | FieldDataType.stringLookup | FieldDataType.longFormString | FieldDataType.molang | FieldDataType.localizableString;
    static getFieldById(formDefinition: IFormDefinition, fieldId: string): IField;
    static getFieldTypeDescription(fieldType: FieldDataType): "Integer number" | "Boolean true/false" | "Decimal number" | "String from a list of choices" | "Integer number from a list of choices" | "Boolean 0/1" | "Large number" | "x, y, z coordinate array" | "integer x, y, z coordinate array" | "Longer descriptive text" | "Named set of objects" | "Array of objects" | "Object" | "Array of strings" | "Range of integers" | "Range of floats" | "Minecraft filter" | "Array of Minecraft Event Triggers" | "Percent Range" | "Minecraft Event Trigger" | "Minecraft Event Reference" | "Array of longer descriptive text" | "Keyed set of strings" | "Version" | "Unique Id" | "Keyed collection of boolean values" | "Keyed collection of string arrays" | "Array of keyed string sets" | "Keyed set of keyed string sets" | "Keyed set of numbers" | "Array of numbers" | "a, b coordinate array" | "Localizable String" | "String" | "Molang" | "Molang array";
    /**
     * Generate a natural language summary of an object based on its form definition.
     *
     * This method loads the summarizer associated with the form (if one exists)
     * and evaluates it against the provided data to produce human-readable phrases.
     *
     * @param data The data object to summarize
     * @param formPath Path to the form definition (e.g., "entity/minecraft_health")
     * @param options Optional evaluation options
     * @returns Result containing phrases and formatted output
     *
     * @example
     * const result = await DataFormUtilities.generateSummary(
     *   { max: 500, value: 500 },
     *   "entity/minecraft_health"
     * );
     * console.log(result.asCompleteSentence);
     * // "This entity has god-tier health (500 HP)."
     */
    static generateSummary(data: object, formPath: string, options?: ISummarizerOptions): Promise<ISummarizerResult>;
    /**
     * Generate a summary and format it as a complete sentence.
     *
     * @param data The data object to summarize
     * @param formPath Path to the form definition
     * @param prefix Optional prefix for the sentence (default: "This entity ")
     * @returns A complete sentence describing the object, or empty string if no summarizer
     *
     * @example
     * const sentence = await DataFormUtilities.generateSummaryAsSentence(
     *   { max: 100 },
     *   "entity/minecraft_health",
     *   "This mob "
     * );
     * // "This mob has extremely high health, on par with an Iron Golem (100 HP)."
     */
    static generateSummaryAsSentence(data: object, formPath: string, prefix?: string): Promise<string>;
    /**
     * Load a summarizer definition by ID.
     *
     * The ID format matches subFormId: "category/name" or just "name".
     * Does NOT include the .summarizer.json suffix.
     *
     * @param summarizerId ID of the summarizer (e.g., "entity/minecraft_health" or "minecraft_health")
     * @param category Optional category subfolder (e.g., "entity", "block") - used if ID doesn't include category
     * @returns The summarizer definition, or undefined if not found
     *
     * @example
     * // These are equivalent:
     * loadSummarizerById("entity/minecraft_health")
     * loadSummarizerById("minecraft_health", "entity")
     */
    static loadSummarizerById(summarizerId: string, category?: string): Promise<ISummarizer | undefined>;
    /**
     * Evaluate a summarizer directly against data.
     *
     * Use this when you already have the summarizer loaded and want to
     * avoid the overhead of loading it from disk.
     *
     * @param summarizer The summarizer definition
     * @param data The data object to summarize
     * @param form Optional form definition for sample lookup
     * @param options Optional evaluation options
     * @returns Result containing phrases and formatted output
     */
    static evaluateSummarizer(summarizer: ISummarizer, data: object, form?: IFormDefinition, options?: ISummarizerOptions): ISummarizerResult;
    /**
     * Get a preview of property names for an object field.
     * Returns a string like "{ description, components, events, ... }" for objects with many properties,
     * or "{ prop1, prop2 }" for objects with few properties.
     *
     * This is useful for displaying concise type information in hovers and tooltips.
     *
     * @param field The field to inspect
     * @returns A formatted string preview of property names, or null if not applicable
     */
    static getObjectPropertyPreview(field: IField): string | null;
    /**
     * Get the child properties of a field (what this field contains).
     * Returns the field's own subForm/subFields, or the referenced subFormId's fields.
     * Returns null if the field doesn't have child properties.
     *
     * This supports multiple resolution strategies:
     * 1. subFormId reference - looks up in the provided forms dictionary
     * 2. Inline subForm - embedded form definition
     * 3. subFields - dictionary-style field definitions
     *
     * @param field The field to inspect
     * @param formsBySubFormId Optional dictionary of forms keyed by subFormId for resolving references
     * @returns Array of child fields, or null if none found
     */
    static getFieldChildProperties(field: IField, formsBySubFormId?: Record<string, IFormDefinition>): IField[] | null;
}