@zcomponent/core 1.14.3 → 1.15.0-beta

package/lib/types.d.ts

@@ -1,9 +1,19 @@
 import { EntityPropOverride } from './data/core';
+/**
+ * Interface representing the base structure for a type definition.
+ *
+ * This interface is used as a foundation for more specific type definitions, providing common properties like comments and type hints.
+ */
 export interface BaseType {
     comments?: string[];
     typeHint?: TypeHint;
     isObservable?: boolean;
 }
+/**
+ * Enumeration of type names used in type definitions.
+ *
+ * This enum lists different kinds of type names that can be used to represent various data types in a type definition.
+ */
 export declare enum TypeName {
     String = "string",
     Number = "number",
@@ -18,36 +28,81 @@ export declare enum TypeName {
     Event = "event",
     Entity = "entity"
 }
+/**
+ * Type definition for a string primitive.
+ *
+ * This interface extends BaseType and is used specifically for defining a string type.
+ */
 export interface StringPrimitiveType extends BaseType {
     name: 'string';
 }
+/**
+ * Type definition for a number primitive.
+ *
+ * This interface extends BaseType and is used specifically for defining a number type.
+ */
 export interface NumberPrimitiveType extends BaseType {
     name: 'number';
 }
+/**
+ * Type definition for a boolean primitive.
+ *
+ * This interface extends BaseType and is used specifically for defining a boolean type.
+ */
 export interface BooleanPrimitiveType extends BaseType {
     name: 'boolean';
 }
+/**
+ * Type definition for a literal type.
+ *
+ * This interface extends BaseType and is used for defining literal types, which represent specific values.
+ */
 export interface LiteralType extends BaseType {
     name: 'literal';
     value?: string | number | boolean | null;
     isUndefined?: boolean;
 }
+/**
+ * Type definition for an array type.
+ *
+ * This interface extends BaseType and represents an array type, specifying the type of elements the array contains.
+ */
 export interface ArrayType extends BaseType {
     name: 'array';
     child: Type;
 }
+/**
+ * Type definition for a tuple type.
+ *
+ * This interface extends BaseType and represents a tuple type, specifying the types of elements and their order in the tuple.
+ */
 export interface TupleType extends BaseType {
     name: 'tuple';
     children: Type[];
     names?: string[];
 }
+/**
+ * Type definition for a union type.
+ *
+ * This interface extends BaseType and represents a union type, which can be one of several specified types.
+ */
 export interface UnionType extends BaseType {
     name: 'union';
     children: Type[];
 }
+/**
+ * Type definition for an unknown type.
+ *
+ * This interface extends BaseType and represents a type that is unspecified or unknown.
+ */
 export interface UnknownType extends BaseType {
     name: 'unknown';
 }
+/**
+ * Type definition for an enum type.
+ *
+ * This interface extends BaseType and is used for defining enumeration types, specifying the possible values an enum can take.
+ */
 export interface EnumType extends BaseType {
     name: 'enum';
     values: {
@@ -57,18 +112,42 @@ export interface EnumType extends BaseType {
         [id: string]: string[];
     };
 }
+/**
+ * Type definition for a function type.
+ *
+ * This interface extends BaseType and represents a function type, detailing the function's arguments and return type.
+ */
 export interface FunctionType extends BaseType {
     name: 'function';
     args: Prop[];
     ret?: Type;
 }
+/**
+ * Type definition for an event type.
+ *
+ * This interface extends BaseType and is used specifically for defining an event type.
+ */
 export interface EventType extends BaseType {
     name: 'event';
 }
+/** Internal use comment is sufficient for EntityType
+ * @internal
+ * @notes for internal use
+ */
 export interface EntityType extends BaseType {
     name: 'entity';
 }
+/**
+ * Union type representing all possible type definitions.
+ *
+ * This type aggregates all specific type interfaces into a single type that can represent any of them.
+ */
 export type Type = StringPrimitiveType | NumberPrimitiveType | BooleanPrimitiveType | ArrayType | TupleType | UnknownType | EnumType | UnionType | LiteralType | FunctionType | EventType | EntityType;
+/**
+ * Enumeration of type hints used to provide additional information about a type.
+ *
+ * This enum provides specific hints that can be used to give more context about how a type should be interpreted or displayed.
+ */
 export declare enum TypeHint {
     'proportion' = "proportion",
     'color-norm-rgb' = "color-norm-rgb",
@@ -87,6 +166,11 @@ export declare enum TypeHint {
     'emailaddress' = "emailaddress",
     'url' = "url"
 }
+/**
+ * Enumeration of values types used in a values definition.
+ *
+ * This enum lists different kinds of values types that can be used in a values definition, representing various data sources or formats.
+ */
 export declare enum ValuesType {
     'files' = "files",
     'animations' = "animations",
@@ -100,10 +184,20 @@ export declare enum ValuesType {
     'layerids' = "layerids",
     'streamids' = "streamids"
 }
+/**
+ * Interface representing a values definition.
+ *
+ * This interface defines the structure for a values definition, specifying the type of values and any associated parameters.
+ */
 export interface Values {
     type: ValuesType;
     param: string;
 }
+/**
+ * Interface representing a property definition.
+ *
+ * This interface defines the structure for a property, including its name, type, default value, and other optional settings.
+ */
 export interface Prop {
     name: string;
     type: Type;
@@ -121,6 +215,11 @@ export interface Prop {
     isConstructorProp?: boolean;
     deprecated?: boolean;
 }
+/**
+ * Interface representing a default child object in a component or behavior definition.
+ *
+ * This interface defines the structure for specifying default children of a component or behavior, including their type and initial properties.
+ */
 export interface DefaultChild {
     label: string;
     type: string;
@@ -128,7 +227,17 @@ export interface DefaultChild {
         [id: string]: any;
     };
 }
+/**
+ * Type representing the category of a component, behavior, or context.
+ *
+ * This type categorizes elements as either a component, behavior, or context.
+ */
 export type ComponentInfoType = 'component' | 'behavior' | 'context';
+/**
+ * Interface representing information about a component.
+ *
+ * This interface defines the structure for specifying details about a component, including its name, file location, type, properties, and other attributes.
+ */
 export interface ComponentInfo {
     name: string;
     file: string;
@@ -153,6 +262,11 @@ export interface ComponentInfo {
     };
     deprecated?: boolean;
 }
+/**
+ * Interface representing information about a value.
+ *
+ * This interface defines the structure for specifying details about a value, including its name, file location, type, and comments.
+ */
 export interface ValueInfo {
     name: string;
     file: string;
@@ -160,6 +274,11 @@ export interface ValueInfo {
     type: Type;
     comments?: string[];
 }
+/**
+ * Interface representing information about a previewer.
+ *
+ * This interface defines the structure for specifying details about a previewer, including its name, file location, and file pattern.
+ */
 export interface PreviewInfo {
     name: string;
     file: string;
@@ -167,9 +286,19 @@ export interface PreviewInfo {
     comments?: string[];
     filePattern: string;
 }
+/**
+ * Interface representing information about a stream.
+ *
+ * This interface defines the structure for specifying details about a stream, including the property path associated with the stream.
+ */
 export interface StreamInfo {
     property: (string | number)[];
 }
+/**
+ * Interface representing information about types defined in a source file.
+ *
+ * This interface defines the structure for organizing information about components, values, and previewers defined in a source file.
+ */
 export interface SourceFileTypeInfo {
     components: {
         [id: string]: ComponentInfo;
@@ -181,29 +310,115 @@ export interface SourceFileTypeInfo {
         [id: string]: PreviewInfo;
     };
 }
+/**
+ * Type representing a mapping of file names to their respective type information.
+ *
+ * This type maps file names to SourceFileTypeInfo, providing an organized structure for storing type information associated with different files.
+ */
 export type TypeInfoByFileName = {
     [id: string]: SourceFileTypeInfo;
 };
+/**
+ * Checks if two types are compatible.
+ *
+ * This function compares two Type objects to determine if they are compatible, considering their names and specific type details.
+ * @param a - The first type for comparison.
+ * @param b - The second type for comparison.
+ * @returns True if the types are compatible, otherwise false.
+ */
 export declare function areTypesCompatible(a: Type, b: Type): boolean;
+/**
+ * Merges two sets of values definitions.
+ *
+ * This function combines two arrays of Values objects, merging them into a single array while avoiding duplicates.
+ * @param a - The first array of values definitions.
+ * @param b - The second array of values definitions.
+ * @returns An array of merged values definitions, or undefined if both inputs are undefined.
+ */
 export declare function mergeValues(a: Values[] | undefined, b: Values[] | undefined): Values[] | undefined;
+/**
+ * Merges two property definitions into one.
+ *
+ * This function combines two Prop objects into a single Prop object, merging their attributes where possible.
+ * @param a - The first property definition.
+ * @param b - The second property definition.
+ * @returns A merged property definition, or undefined if they cannot be merged.
+ */
 export declare function mergeProps(a: Prop, b: Prop): Prop | undefined;
+/**
+ * Merges two types into one, if they are compatible.
+ *
+ * @param a - The first type to merge.
+ * @param b - The second type to merge.
+ * @returns A merged type, or undefined if the types are not compatible.
+ */
 export declare function mergeTypes(a: Type, b: Type): Type | undefined;
+/**
+ * Represents information about a template, including its name, content, and optional file extension.
+ *
+ * @interface
+ * @property name - The name of the template.
+ * @property content - The content of the template.
+ * @property extn - Optional. The file extension associated with the template.
+ */
 export interface TemplateInfo {
     name: string;
     content: string;
     extn?: string;
 }
+/**
+ * Describes a file generator with its name, URL, and an optional icon.
+ *
+ * @interface
+ * @property name - The name of the file generator.
+ * @property url - The URL where the file generator is located or can be accessed.
+ * @property icon - Optional. A URL or a path to an icon representing the file generator.
+ */
 export interface FileGenerator {
     name: string;
     url: string;
     icon?: string;
 }
+/**
+ * Converts a filename to a symbol path by removing certain file extension patterns.
+ *
+ * @param f - The filename to convert.
+ * @returns A symbol path derived from the given filename.
+ */
 export declare function symbolPathFromFilename(f: string): string;
+/**
+ * Checks if a given value is valid for a specified type.
+ *
+ * @param def - The value to validate.
+ * @param t - The type against which the value is to be validated.
+ * @param allowUndefined - A boolean indicating whether undefined values are allowed.
+ * @returns A boolean indicating whether the value is valid for the given type.
+ */
 export declare function isValidValueForType(def: any, t: Type, allowUndefined?: boolean): boolean;
+/**
+ * Generates a TypeScript output string for a given type.
+ *
+ * @param t - The type to generate output for.
+ * @param alwaysBasic - A boolean indicating whether to always use the basic type representation.
+ * @returns A string representing the type in TypeScript syntax.
+ */
 export declare function outputForType(t: Type, alwaysBasic?: boolean): string;
+/**
+ * Checks if overrides in two objects are compatible with each other.
+ *
+ * @param a - The first object containing entity prop overrides.
+ * @param b - The second object containing entity prop overrides.
+ * @returns A boolean indicating whether the overrides in both objects are compatible.
+ */
 export declare function overridesAreCompatible(a: {
     [path: string]: EntityPropOverride;
 }, b: {
     [path: string]: EntityPropOverride;
 }): boolean;
+/**
+ * Generates a default value for a given type.
+ *
+ * @param t - The type for which to generate a default value.
+ * @returns A default value appropriate for the given type.
+ */
 export declare function defaultValueForType(t: Type): any;

package/lib/types.js

@@ -1,5 +1,10 @@
-import { EntityPropOverrideType, FunctionCallType } from './data/core';
+import { EntityPropOverrideType, FunctionCallType, } from './data/core';
 import { getSafeKeyName } from './selectors';
+/**
+ * Enumeration of type names used in type definitions.
+ *
+ * This enum lists different kinds of type names that can be used to represent various data types in a type definition.
+ */
 export var TypeName;
 (function (TypeName) {
     TypeName["String"] = "string";
@@ -15,6 +20,11 @@ export var TypeName;
     TypeName["Event"] = "event";
     TypeName["Entity"] = "entity";
 })(TypeName || (TypeName = {}));
+/**
+ * Enumeration of type hints used to provide additional information about a type.
+ *
+ * This enum provides specific hints that can be used to give more context about how a type should be interpreted or displayed.
+ */
 export var TypeHint;
 (function (TypeHint) {
     TypeHint["proportion"] = "proportion";
@@ -34,6 +44,11 @@ export var TypeHint;
     TypeHint["emailaddress"] = "emailaddress";
     TypeHint["url"] = "url";
 })(TypeHint || (TypeHint = {}));
+/**
+ * Enumeration of values types used in a values definition.
+ *
+ * This enum lists different kinds of values types that can be used in a values definition, representing various data sources or formats.
+ */
 export var ValuesType;
 (function (ValuesType) {
     ValuesType["files"] = "files";
@@ -48,6 +63,14 @@ export var ValuesType;
     ValuesType["layerids"] = "layerids";
     ValuesType["streamids"] = "streamids";
 })(ValuesType || (ValuesType = {}));
+/**
+ * Checks if values in two objects are compatible.
+ *
+ * This function compares two objects containing string or number values to determine if they are compatible.
+ * @param l - The first object for comparison.
+ * @param r - The second object for comparison.
+ * @returns True if the objects are compatible, otherwise false.
+ */
 function valuesCompatible(l, r) {
     if (!l && !r)
         return true;
@@ -59,6 +82,14 @@ function valuesCompatible(l, r) {
     }
     return true;
 }
+/**
+ * Checks if two types are compatible.
+ *
+ * This function compares two Type objects to determine if they are compatible, considering their names and specific type details.
+ * @param a - The first type for comparison.
+ * @param b - The second type for comparison.
+ * @returns True if the types are compatible, otherwise false.
+ */
 export function areTypesCompatible(a, b) {
     if (a.name !== b.name)
         return false;
@@ -118,6 +149,14 @@ export function areTypesCompatible(a, b) {
     }
     return true;
 }
+/**
+ * Merges two sets of values definitions.
+ *
+ * This function combines two arrays of Values objects, merging them into a single array while avoiding duplicates.
+ * @param a - The first array of values definitions.
+ * @param b - The second array of values definitions.
+ * @returns An array of merged values definitions, or undefined if both inputs are undefined.
+ */
 export function mergeValues(a, b) {
     if (a === undefined && b === undefined)
         return undefined;
@@ -137,6 +176,14 @@ export function mergeValues(a, b) {
     }
     return ret;
 }
+/**
+ * Merges two property definitions into one.
+ *
+ * This function combines two Prop objects into a single Prop object, merging their attributes where possible.
+ * @param a - The first property definition.
+ * @param b - The second property definition.
+ * @returns A merged property definition, or undefined if they cannot be merged.
+ */
 export function mergeProps(a, b) {
     if (a.name !== b.name)
         return;
@@ -165,10 +212,24 @@ export function mergeProps(a, b) {
         readonly: a.readonly,
     };
 }
+/**
+ * Merges comments from two sources into a unique set of comments.
+ *
+ * @param a - An array of strings representing the first set of comments.
+ * @param b - An array of strings representing the second set of comments.
+ * @returns An array of merged unique comments.
+ */
 function mergeComments(a, b) {
     const s = new Set([...a, ...b]);
     return [...s.values()];
 }
+/**
+ * Merges value comments for each identifier in two given objects.
+ *
+ * @param a - An object where keys are identifiers and values are arrays of comments.
+ * @param b - Another object with the same structure to merge with.
+ * @returns An object with merged comments for each identifier.
+ */
 function mergeValueComments(a, b) {
     const ret = {};
     for (const [k, v] of Object.entries(a)) {
@@ -176,6 +237,13 @@ function mergeValueComments(a, b) {
     }
     return ret;
 }
+/**
+ * Merges two tuple type names if they are identical.
+ *
+ * @param a - The first tuple type to merge.
+ * @param b - The second tuple type to merge.
+ * @returns An array of merged tuple names, or undefined if they cannot be merged.
+ */
 function mergeTupleNames(a, b) {
     if (!a.names || !b.names)
         return;
@@ -187,6 +255,13 @@ function mergeTupleNames(a, b) {
     }
     return a.names;
 }
+/**
+ * Merges two types into one, if they are compatible.
+ *
+ * @param a - The first type to merge.
+ * @param b - The second type to merge.
+ * @returns A merged type, or undefined if the types are not compatible.
+ */
 export function mergeTypes(a, b) {
     if (!areTypesCompatible(a, b))
         return;
@@ -283,9 +358,23 @@ export function mergeTypes(a, b) {
     }
 }
 const regex = new RegExp(/((\.tsx?)|(\.d\.ts)|(\.jsx?))$/, 'i');
+/**
+ * Converts a filename to a symbol path by removing certain file extension patterns.
+ *
+ * @param f - The filename to convert.
+ * @returns A symbol path derived from the given filename.
+ */
 export function symbolPathFromFilename(f) {
     return f.replace(regex, '');
 }
+/**
+ * Checks if a given value is valid for a specified type.
+ *
+ * @param def - The value to validate.
+ * @param t - The type against which the value is to be validated.
+ * @param allowUndefined - A boolean indicating whether undefined values are allowed.
+ * @returns A boolean indicating whether the value is valid for the given type.
+ */
 export function isValidValueForType(def, t, allowUndefined) {
     if (allowUndefined && typeof def === 'undefined')
         return true;
@@ -366,6 +455,13 @@ export function isValidValueForType(def, t, allowUndefined) {
     }
     return false;
 }
+/**
+ * Generates a TypeScript output string for a given type.
+ *
+ * @param t - The type to generate output for.
+ * @param alwaysBasic - A boolean indicating whether to always use the basic type representation.
+ * @returns A string representing the type in TypeScript syntax.
+ */
 export function outputForType(t, alwaysBasic = false) {
     if (t.isObservable && !alwaysBasic)
         return `Observable<${getBasicType(t)}>`;
@@ -401,6 +497,13 @@ function getBasicType(t) {
             return 'Event';
     }
 }
+/**
+ * Checks if overrides in two objects are compatible with each other.
+ *
+ * @param a - The first object containing entity prop overrides.
+ * @param b - The second object containing entity prop overrides.
+ * @returns A boolean indicating whether the overrides in both objects are compatible.
+ */
 export function overridesAreCompatible(a, b) {
     const bkeys = new Set(Object.keys(b));
     for (const [p, obj] of Object.entries(a)) {
@@ -457,6 +560,12 @@ function overrideAreCompatible(a, b) {
         return false;
     return true;
 }
+/**
+ * Generates a default value for a given type.
+ *
+ * @param t - The type for which to generate a default value.
+ * @returns A default value appropriate for the given type.
+ */
 export function defaultValueForType(t) {
     switch (t.name) {
         case 'array':

package/lib/validators.d.ts

@@ -3,8 +3,35 @@ import type { ZValues } from './values/values';
 interface Issue {
     text: string;
 }
+/**
+ * Validates the structure of an `Import`.
+ *
+ * @param i - The `Import` to validate.
+ * @returns An array of `Issue` objects, each representing a validation issue found.
+ */
 export declare const validateImport: (i: Import) => Issue[];
+/**
+ * Validates the top-level structure of ZValues.
+ *
+ * @param url - The URL associated with the ZValues.
+ * @param values - The `ZValues` object to validate.
+ * @returns An array of `Issue` objects, each representing a validation issue found.
+ */
 export declare const validatorZValuesTopLevel: (url: string, values: ZValues) => Issue[];
+/**
+ * Validates the top-level structure of a ZComponentData object.
+ *
+ * @param url - The URL associated with the ZComponentData.
+ * @param component - The `ZComponentData` object to validate.
+ * @returns An array of `Issue` objects, each representing a validation issue found.
+ */
 export declare const validatorZcomponentTopLevel: (url: string, component: ZComponentData) => Issue[];
+/**
+ * Validates the structure and consistency of a ZComponent's node.
+ *
+ * @param node - The `NodeData` of the ZComponent's node to validate.
+ * @param nodeId - The expected ID of the node.
+ * @returns An array of `Issue` objects, each representing a validation issue found.
+ */
 export declare const validatorZcomponentComponent: (node: NodeData, nodeId: string) => Issue[];
 export {};

package/lib/validators.js

@@ -1,3 +1,9 @@
+/**
+ * Validates the structure of an `Import`.
+ *
+ * @param i - The `Import` to validate.
+ * @returns An array of `Issue` objects, each representing a validation issue found.
+ */
 export const validateImport = (i) => {
     if (typeof i !== 'string')
         return [{ text: 'Import structure is invalid' }];
@@ -5,12 +11,26 @@ export const validateImport = (i) => {
         return [{ text: 'Import structure is invalid' }];
     return [];
 };
+/**
+ * Validates the top-level structure of ZValues.
+ *
+ * @param url - The URL associated with the ZValues.
+ * @param values - The `ZValues` object to validate.
+ * @returns An array of `Issue` objects, each representing a validation issue found.
+ */
 export const validatorZValuesTopLevel = (url, values) => {
     if (typeof values !== 'object' || typeof values.keys !== 'object' || typeof values.values !== 'object' || typeof values.variantsByID !== 'object') {
         return [{ text: 'values structure is invalid' }];
     }
     return [];
 };
+/**
+ * Validates the top-level structure of a ZComponentData object.
+ *
+ * @param url - The URL associated with the ZComponentData.
+ * @param component - The `ZComponentData` object to validate.
+ * @returns An array of `Issue` objects, each representing a validation issue found.
+ */
 export const validatorZcomponentTopLevel = (url, component) => {
     if (typeof component !== 'object' ||
         typeof component.nodes !== 'object' ||
@@ -27,6 +47,13 @@ export const validatorZcomponentTopLevel = (url, component) => {
         return [{ text: 'Component root node does not exist' }];
     return [];
 };
+/**
+ * Validates the structure and consistency of a ZComponent's node.
+ *
+ * @param node - The `NodeData` of the ZComponent's node to validate.
+ * @param nodeId - The expected ID of the node.
+ * @returns An array of `Issue` objects, each representing a validation issue found.
+ */
 export const validatorZcomponentComponent = (node, nodeId) => {
     if (typeof node !== 'object')
         return [{ text: 'Node not object' }];

package/lib/values/values.d.ts

@@ -37,6 +37,11 @@ export type ZVariant = LocaleVariant | QueryStringVariant | UserAgentVariant | D
 export declare class ValuesManager {
     private valuesString;
     private profile;
+    /**
+     * Creates an instance of ValuesManager.
+     * @param valuesString - The values string.
+     * @param states - The states.
+     */
     constructor(valuesString: string, states: Map<string, any>);
     private getValueForKey;
     private getEnabledStateOfVariant;

package/lib/values/values.js

@@ -31,6 +31,11 @@ export function getTypeForVariant(variant) {
 }
 export class ValuesManager {
     // TODO: Fix this any
+    /**
+     * Creates an instance of ValuesManager.
+     * @param valuesString - The values string.
+     * @param states - The states.
+     */
     constructor(valuesString, states) {
         this.valuesString = valuesString;
         this.profile = new Profile();