@zcomponent/core 1.14.3 → 1.15.0-beta

package/lib/selectors.d.ts

@@ -1,15 +1,69 @@
 import { BehaviorByID, EntityPropOverride, Import, NodeByID, ParsedImport, Props, ZComponentData } from './data/core';
 import * as Data from './data';
 import { ZValues } from './values/values';
+/**
+ * Parses an import string into a tuple containing the import path and import name.
+ *
+ * @param i - The import string to parse.
+ * @returns A tuple where the first element is the import path and the second element is the import name.
+ */
 export declare function parseImport(i: Import): ParsedImport;
+/**
+ * Constructs an import string from given parameters.
+ *
+ * @param from - The source file path.
+ * @param destFile - The destination file path.
+ * @param imp - The import name.
+ * @returns A string representing the constructed import.
+ */
 export declare function constructImport(from: string, destFile: string, imp: string): string;
+/**
+ * Generates a script name from a given string, ensuring uniqueness within a specified context.
+ *
+ * @param n - The input string to generate the script name from.
+ * @param requireUniqueIn - The context (array or object) in which the generated name should be unique.
+ * @returns A string representing the generated script name.
+ */
 export declare function getScriptName(n: string, requireUniqueIn: string[] | {
     [k: string]: any;
 }): string;
+/**
+ * Generates a script name for a behavior label, ensuring uniqueness within the context of a ZComponent's nodes.
+ *
+ * @param zcomp - The ZComponent data.
+ * @param nodeID - The node ID associated with the behavior.
+ * @param label - The behavior label.
+ * @returns A string representing the generated script name for the behavior.
+ */
 export declare function getScriptNameForBehaviorLabel(zcomp: ZComponentData, nodeID: string, label: string): string;
+/**
+ * Generates a script name for a node label, ensuring uniqueness within the context of a ZComponent's nodes.
+ *
+ * @param zcomp - The ZComponent data.
+ * @param label - The node label.
+ * @returns A string representing the generated script name for the node.
+ */
 export declare function getScriptNameForNodeLabel(zcomp: ZComponentData, label: string): string;
+/**
+ * Checks if a given string is a valid variable name.
+ *
+ * @param n - The string to check.
+ * @returns True if the string is a valid variable name, otherwise false.
+ */
 export declare function isValidVariableName(n: string): boolean;
+/**
+ * Generates a variable name from an import statement.
+ *
+ * @param imp - The parsed import statement.
+ * @returns A string representing the generated variable name.
+ */
 export declare function variableNameFromImport(imp: ParsedImport): string;
+/**
+ * Organizes entity property overrides by entity ID and property name.
+ *
+ * @param entityPropOverrides - An object containing entity property overrides.
+ * @returns An object organized by entity ID and property name, containing the overrides.
+ */
 export type EntityPropOverrideByEntityPropPath = {
     [entityID: string]: {
         [propName: string]: {
@@ -17,19 +71,79 @@ export type EntityPropOverrideByEntityPropPath = {
         };
     };
 };
+/**
+ * Generates a summary description for the destination of an entity property override.
+ *
+ * @param o - The entity property override object.
+ * @returns A string representing the summary description of the override's destination.
+ */
 export declare function entityPropOverrideByEntityAndProp(entityPropOverrides: {
     [id: string]: EntityPropOverride;
 }): EntityPropOverrideByEntityPropPath;
+/**
+ * Generates a summary description for the destination of an entity property override.
+ *
+ * @param o - The entity property override object.
+ * @returns A string representing the summary description of the override's destination.
+ */
 export declare function summaryForEntityPropOverrideDestination(o: EntityPropOverride): string;
+/**
+ * Generates a TypeScript type definition for a ZComponent.
+ *
+ * This function creates a type definition script for a ZComponent based on its nodes, properties, constructor properties, script names, layers, and behaviors.
+ *
+ * @param nodes - The nodes of the ZComponent.
+ * @param props - The properties of the ZComponent.
+ * @param constructorProps - The constructor properties of the ZComponent.
+ * @param scriptNames - The script names for the nodes and behaviors.
+ * @param layers - The layers of the ZComponent's animation.
+ * @param behaviors - The behaviors of the ZComponent.
+ * @returns A string containing the TypeScript type definition for the ZComponent.
+ */
 export declare const typeDefinitionForComponent: (nodes: NodeByID, props: Props, constructorProps: Props | undefined, scriptNames: {
     [id: string]: {
         [id: string]: boolean;
     };
 } | undefined, layers: Data.ByID<Data.Layer>, behaviors: BehaviorByID) => string;
+/**
+ * Sanitizes a key name to ensure it is safe for use in scripting.
+ *
+ * @param n - The original key name.
+ * @returns A sanitized, script-safe key name.
+ */
 export declare function getSafeKeyName(n: string): string;
+/**
+ * Extracts and groups property tracks by their associated entity ID from a given clip.
+ *
+ * @param clip - The clip containing property tracks.
+ * @returns An object mapping entity IDs to their respective property tracks.
+ */
 export declare function propertyTracksByEntityID(clip: Data.Clip): {
     [id: string]: Data.PropertyTrack[];
 };
+/**
+ * Generates a behavior block for a node, based on the behaviors and their IDs.
+ *
+ * @param behaviors - An object containing behavior data.
+ * @param behaviorIDs - An array of behavior IDs.
+ * @param importMapping - A map of behavior types to their import names.
+ * @returns A string representing the behavior block for the node.
+ */
 export declare function getBehaviorBlockForNode(behaviors: BehaviorByID, behaviorIDs: string[], importMapping: Map<string, string>): string;
+/**
+ * Removes the file extension from an import name, if it ends with '.ts'.
+ *
+ * @param imp - The import name to process.
+ * @returns The import name without the '.ts' extension.
+ */
 export declare function importNameWithoutExt(imp: string): string;
+/**
+ * Generates a TypeScript type definition for ZValues.
+ *
+ * This function creates a type definition script for ZValues based on the values and their associated URL.
+ *
+ * @param values - The ZValues instance.
+ * @param url - The URL associated with the values.
+ * @returns A string containing the TypeScript type definition for ZValues.
+ */
 export declare const typeDefinitionForZValues: (values: ZValues, url: string) => string;

package/lib/selectors.js

@@ -4,6 +4,12 @@ import { outputForType } from './types';
 import * as Data from './data';
 import * as VALUES from './values/valuesmutator';
 import { computeBehaviorHierarchy } from './data';
+/**
+ * Parses an import string into a tuple containing the import path and import name.
+ *
+ * @param i - The import string to parse.
+ * @returns A tuple where the first element is the import path and the second element is the import name.
+ */
 export function parseImport(i) {
     if (typeof i !== 'string')
         return ['', ''];
@@ -12,6 +18,14 @@ export function parseImport(i) {
         return [i, 'default'];
     return [i.substr(0, indx), i.substr(indx + 1)];
 }
+/**
+ * Constructs an import string from given parameters.
+ *
+ * @param from - The source file path.
+ * @param destFile - The destination file path.
+ * @param imp - The import name.
+ * @returns A string representing the constructed import.
+ */
 export function constructImport(from, destFile, imp) {
     if (destFile.indexOf('/node_modules/') === 0) {
         return destFile.substr('/node_modules/'.length) + '#' + imp;
@@ -86,6 +100,13 @@ const reservedWords = [
     'with',
     'yield',
 ];
+/**
+ * Generates a script name from a given string, ensuring uniqueness within a specified context.
+ *
+ * @param n - The input string to generate the script name from.
+ * @param requireUniqueIn - The context (array or object) in which the generated name should be unique.
+ * @returns A string representing the generated script name.
+ */
 export function getScriptName(n, requireUniqueIn) {
     const existing = new Set(Array.isArray(requireUniqueIn) ? requireUniqueIn : Object.keys(requireUniqueIn));
     if (n === undefined || n.length === 0) {
@@ -109,6 +130,14 @@ export function getScriptName(n, requireUniqueIn) {
     }
     return finalname;
 }
+/**
+ * Generates a script name for a behavior label, ensuring uniqueness within the context of a ZComponent's nodes.
+ *
+ * @param zcomp - The ZComponent data.
+ * @param nodeID - The node ID associated with the behavior.
+ * @param label - The behavior label.
+ * @returns A string representing the generated script name for the behavior.
+ */
 export function getScriptNameForBehaviorLabel(zcomp, nodeID, label) {
     const uniques = [];
     const behaviorsByNode = computeBehaviorHierarchy(zcomp.behaviors);
@@ -123,6 +152,13 @@ export function getScriptNameForBehaviorLabel(zcomp, nodeID, label) {
     }
     return getScriptName(label, uniques);
 }
+/**
+ * Generates a script name for a node label, ensuring uniqueness within the context of a ZComponent's nodes.
+ *
+ * @param zcomp - The ZComponent data.
+ * @param label - The node label.
+ * @returns A string representing the generated script name for the node.
+ */
 export function getScriptNameForNodeLabel(zcomp, label) {
     const uniques = [];
     for (const node of Object.values(zcomp.nodes)) {
@@ -133,9 +169,21 @@ export function getScriptNameForNodeLabel(zcomp, label) {
     return getScriptName(label, uniques);
 }
 const variableNameRegex = new RegExp(/[a-zA-Z_$][0-9a-zA-Z_$]*/);
+/**
+ * Checks if a given string is a valid variable name.
+ *
+ * @param n - The string to check.
+ * @returns True if the string is a valid variable name, otherwise false.
+ */
 export function isValidVariableName(n) {
     return variableNameRegex.test(n);
 }
+/**
+ * Generates a variable name from an import statement.
+ *
+ * @param imp - The parsed import statement.
+ * @returns A string representing the generated variable name.
+ */
 export function variableNameFromImport(imp) {
     if (imp[1] === 'default' && typeof imp[0] === 'string') {
         const parts = imp[0].split(path.sep);
@@ -145,6 +193,12 @@ export function variableNameFromImport(imp) {
         return imp[1];
     return 'unknown';
 }
+/**
+ * Generates a summary description for the destination of an entity property override.
+ *
+ * @param o - The entity property override object.
+ * @returns A string representing the summary description of the override's destination.
+ */
 export function entityPropOverrideByEntityAndProp(entityPropOverrides) {
     const ret = Object.create(null);
     for (const val of Object.values(entityPropOverrides)) {
@@ -159,6 +213,12 @@ export function entityPropOverrideByEntityAndProp(entityPropOverrides) {
     }
     return ret;
 }
+/**
+ * Generates a summary description for the destination of an entity property override.
+ *
+ * @param o - The entity property override object.
+ * @returns A string representing the summary description of the override's destination.
+ */
 export function summaryForEntityPropOverrideDestination(o) {
     switch (o.type) {
         case EntityPropOverrideType.ComponentProp:
@@ -171,7 +231,7 @@ export function summaryForEntityPropOverrideDestination(o) {
             }
             if (typeof imp[1] === 'string')
                 return imp[1] + '.' + o.val;
-            return `?.` + o.val;
+            return '?.' + o.val;
         }
         case EntityPropOverrideType.Import: {
             return o.imp;
@@ -215,10 +275,23 @@ function typeContainsType(p, name) {
     }
     return false;
 }
+/**
+ * Generates a TypeScript type definition for a ZComponent.
+ *
+ * This function creates a type definition script for a ZComponent based on its nodes, properties, constructor properties, script names, layers, and behaviors.
+ *
+ * @param nodes - The nodes of the ZComponent.
+ * @param props - The properties of the ZComponent.
+ * @param constructorProps - The constructor properties of the ZComponent.
+ * @param scriptNames - The script names for the nodes and behaviors.
+ * @param layers - The layers of the ZComponent's animation.
+ * @param behaviors - The behaviors of the ZComponent.
+ * @returns A string containing the TypeScript type definition for the ZComponent.
+ */
 export const typeDefinitionForComponent = (nodes, props, constructorProps, scriptNames, layers, behaviors) => {
     const importMapping = new Map();
     let indx = 0;
-    let importStrings = [];
+    const importStrings = [];
     const behaviorsByNodeID = computeBehaviorHierarchy(behaviors);
     for (const scriptNameNodes of Object.values(scriptNames ?? {})) {
         for (const nodeID of Object.keys(scriptNameNodes)) {
@@ -265,15 +338,19 @@ declare class Comp extends ZComponent {
 	constructor(contextManager: ContextManager, constructorProps: ConstructorProps);
 
 	nodes: {
-${Object.entries(scriptNames ?? {}).map(entry => {
+${Object.entries(scriptNames ?? {})
+        .map(entry => {
         const values = Object.keys(entry[1]);
         if (values.length > 1) {
-            return `\t\t${entry[0]}: {${values.map(e => `${JSON.stringify(e)}: ${importMapping.get(nodes[e].type)}${getBehaviorBlockForNode(behaviors, behaviorsByNodeID[nodes[e].id] ?? [], importMapping)}`).join(', ')}},`;
+            return `\t\t${entry[0]}: {${values
+                .map(e => `${JSON.stringify(e)}: ${importMapping.get(nodes[e].type)}${getBehaviorBlockForNode(behaviors, behaviorsByNodeID[nodes[e].id] ?? [], importMapping)}`)
+                .join(', ')}},`;
         }
         else {
             return `\t\t${entry[0]}: ${importMapping.get(nodes[values[0]].type)}${getBehaviorBlockForNode(behaviors, behaviorsByNodeID[nodes[values[0]].id] ?? [], importMapping)},`;
         }
-    }).join("\n")}
+    })
+        .join('\n')}
 	};
 
 	animation: ${typeForAnimation(layers)}
@@ -284,6 +361,12 @@ ${Object.values(props).map(typeOutputForProp).join('\n\n')}
 export default Comp;
 `;
 };
+/**
+ * Generates a TypeScript type definition for an animation, based on its layer data.
+ *
+ * @param layers - An object containing layer data.
+ * @returns A string representing the TypeScript type for the animation, including layer and clip details.
+ */
 function typeForAnimation(layers) {
     const layersWithScriptNames = Object.values(layers).filter(l => l?.scriptName !== undefined);
     return `Animation & { layers: {
@@ -299,9 +382,21 @@ ${Object.values(clipsWithScriptNames)
         .join('\n')}
 	}};`;
 }
+/**
+ * Sanitizes a comment string by removing potentially harmful characters.
+ *
+ * @param c - The comment string to be sanitized.
+ * @returns A safe comment string.
+ */
 function makeCommentSafe(c) {
     return c.replaceAll('*/', '');
 }
+/**
+ * Generates JSDoc comments for a given property.
+ *
+ * @param prop - The property for which to generate JSDoc comments.
+ * @returns A string containing the JSDoc comments for the property.
+ */
 function getJSDocForProp(prop) {
     let lines = [];
     for (const comment of prop.comments ?? []) {
@@ -327,14 +422,32 @@ function getJSDocForProp(prop) {
     lines = lines.map(entry => '\t * ' + entry);
     return `\t/**\n${lines.join('\n')}\n\t */`;
 }
+/**
+ * Generates TypeScript output for a property, including JSDoc comments.
+ *
+ * @param prop - The property to generate TypeScript output for.
+ * @returns A string representing the TypeScript output for the property.
+ */
 function typeOutputForProp(prop) {
     return `${getJSDocForProp(prop)}
 	public ${prop.name}: Observable<${outputForType(prop.type, true)}>;`;
 }
+/**
+ * Generates TypeScript output for a constructor property, including JSDoc comments.
+ *
+ * @param prop - The constructor property to generate TypeScript output for.
+ * @returns A string representing the TypeScript output for the constructor property.
+ */
 function typeOutputForConstructorProp(prop) {
     return `${getJSDocForProp(prop)}
 	${prop.name}: ${outputForType(prop.type, true)};`;
 }
+/**
+ * Sanitizes a key name to ensure it is safe for use in scripting.
+ *
+ * @param n - The original key name.
+ * @returns A sanitized, script-safe key name.
+ */
 export function getSafeKeyName(n) {
     if (n.length === 0)
         return '_';
@@ -347,6 +460,12 @@ export function getSafeKeyName(n) {
     }
     return scriptname;
 }
+/**
+ * Extracts and groups property tracks by their associated entity ID from a given clip.
+ *
+ * @param clip - The clip containing property tracks.
+ * @returns An object mapping entity IDs to their respective property tracks.
+ */
 export function propertyTracksByEntityID(clip) {
     const ret = Object.create(null);
     for (const track of Object.values(clip.tracks)) {
@@ -360,10 +479,19 @@ export function propertyTracksByEntityID(clip) {
     }
     return ret;
 }
+/**
+ * Generates a behavior block for a node, based on the behaviors and their IDs.
+ *
+ * @param behaviors - An object containing behavior data.
+ * @param behaviorIDs - An array of behavior IDs.
+ * @param importMapping - A map of behavior types to their import names.
+ * @returns A string representing the behavior block for the node.
+ */
 export function getBehaviorBlockForNode(behaviors, behaviorIDs, importMapping) {
     return ` & {
 			behaviors: {
-${behaviorIDs.map((entry, indx) => {
+${behaviorIDs
+        .map((entry, indx) => {
         const behavior = behaviors[entry];
         if (!behavior)
             return '';
@@ -372,15 +500,31 @@ ${behaviorIDs.map((entry, indx) => {
         if (behavior.parent.scriptName)
             ret.push(`\t\t\t\t${behavior.parent.scriptName}: ${type},`);
         return ret.join('\n');
-    }).join('\n')}
+    })
+        .join('\n')}
 			}
 		}`;
 }
+/**
+ * Removes the file extension from an import name, if it ends with '.ts'.
+ *
+ * @param imp - The import name to process.
+ * @returns The import name without the '.ts' extension.
+ */
 export function importNameWithoutExt(imp) {
     if (imp.toLowerCase().endsWith('.ts'))
         return imp.substring(0, imp.length - 3);
     return imp;
 }
+/**
+ * Generates a TypeScript type definition for ZValues.
+ *
+ * This function creates a type definition script for ZValues based on the values and their associated URL.
+ *
+ * @param values - The ZValues instance.
+ * @param url - The URL associated with the values.
+ * @returns A string containing the TypeScript type definition for ZValues.
+ */
 export const typeDefinitionForZValues = (values, url) => {
     const code = [];
     const defaults = VALUES.getTypesAndDefaultsByKey(values);
@@ -393,6 +537,14 @@ export const typeDefinitionForZValues = (values, url) => {
     return `import { Observable } from "@zcomponent/core";
 ${code.join('\n')}`;
 };
+/**
+ * Generates TypeScript output for a ZValue key.
+ *
+ * @param keyName - The name of the ZValue key.
+ * @param _type - The type of the ZValue.
+ * @param defaultValue - The default value for the ZValue.
+ * @returns A string representing the TypeScript output for the ZValue key.
+ */
 function typeOutputForZValueKey(keyName, _type, defaultValue) {
     // TODO: Description
     // const description = value.description ? `@description ${JSON.stringify(value.description)}` : '*';