@zcomponent/core 1.29.0 → 2.0.0-alpha.2

package/lib/types.d.ts

@@ -26,7 +26,9 @@ export declare enum TypeName {
     Enum = "enum",
     Function = "function",
     Event = "event",
-    Entity = "entity"
+    Entity = "entity",
+    ClassInstance = "classinstance",
+    ConstructorForComponent = "constructorforcomponent"
 }
 /**
  * Type definition for a string primitive.
@@ -36,6 +38,9 @@ export declare enum TypeName {
 export interface StringPrimitiveType extends BaseType {
     name: 'string';
 }
+export interface ClassInstanceType extends BaseType {
+    name: 'classinstance';
+}
 /**
  * Type definition for a number primitive.
  *
@@ -137,19 +142,23 @@ export interface EventType extends BaseType {
 export interface EntityType extends BaseType {
     name: 'entity';
 }
+export interface ConstructorForComponentType extends BaseType {
+    name: 'constructorforcomponent';
+}
 /**
  * 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;
+export type Type = StringPrimitiveType | NumberPrimitiveType | BooleanPrimitiveType | ArrayType | TupleType | UnknownType | EnumType | UnionType | LiteralType | FunctionType | EventType | EntityType | ClassInstanceType | ConstructorForComponentType;
 /**
  * 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",
+    proportion = "proportion",
+    range = "range",
     'color-norm-rgb' = "color-norm-rgb",
     'color-norm-rgb-srgb' = "color-norm-rgb-srgb",
     'color-norm-rgb-linear' = "color-norm-rgb-linear",
@@ -165,10 +174,10 @@ export declare enum TypeHint {
     'time-seconds' = "time-seconds",
     'time-milliseconds' = "time-milliseconds",
     'time-hertz' = "time-hertz",
-    'emailaddress' = "emailaddress",
-    'url' = "url",
+    emailaddress = "emailaddress",
+    url = "url",
     'function-emit-component-prop-event' = "function-emit-component-prop-event",
-    'animationcurve' = "animationcurve"
+    animationcurve = "animationcurve"
 }
 /**
  * Enumeration of values types used in a values definition.
@@ -176,19 +185,20 @@ export declare enum TypeHint {
  * 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",
-    'morphTargets' = "morphTargets",
-    'events' = "events",
-    'parentNodes' = "parentNodes",
-    'parentMaterials' = "parentMaterials",
-    'nodelabels' = "nodelabels",
-    'nodeids' = "nodeids",
-    'layerclipids' = "layerclipids",
-    'easings' = "easings",
-    'layerids' = "layerids",
-    'streamids' = "streamids",
-    'behaviorids' = "behaviorids"
+    files = "files",
+    animations = "animations",
+    morphTargets = "morphTargets",
+    events = "events",
+    parentNodes = "parentNodes",
+    parentMaterials = "parentMaterials",
+    nodelabels = "nodelabels",
+    nodeids = "nodeids",
+    layerclipids = "layerclipids",
+    easings = "easings",
+    layerids = "layerids",
+    streamids = "streamids",
+    behaviorids = "behaviorids",
+    components = "components"
 }
 /**
  * Interface representing a values definition.
@@ -428,3 +438,135 @@ export declare function overridesAreCompatible(a: {
  * @returns A default value appropriate for the given type.
  */
 export declare function defaultValueForType(t: Type): any;
+export type ValueOf<T> = T[keyof T];
+/**
+ * Represents a numeric range with specified minimum and maximum bounds.
+ *
+ * @template MIN - The minimum value (defaults to 0)
+ * @template MAX - The maximum value (defaults to 1)
+ *
+ * @example
+ * ```typescript
+ * interface Props {
+ *   opacity: Range<0, 1>;        // 0-1 range for opacity
+ *   volume: Range<0, 100>;       // 0-100 range for volume
+ *   temperature: Range<-20, 50>; // -20 to 50 range for temperature
+ * }
+ * ```
+ */
+export type Range<MIN extends number = 0, MAX extends number = 1> = number;
+/**
+ * Represents an angular measurement with specified units.
+ *
+ * @template UNITS - The angular units ('radians' | 'degrees'), defaults to 'radians'
+ *
+ * @example
+ * ```typescript
+ * interface Props {
+ *   rotation: Angle<'degrees'>;  // Angle in degrees
+ *   phase: Angle<'radians'>;     // Angle in radians (default)
+ *   heading: Angle;              // Defaults to radians
+ * }
+ * ```
+ */
+export type Angle<UNITS extends 'radians' | 'degrees' = 'radians'> = number;
+/**
+ * Represents a project file path with optional glob pattern constraint.
+ *
+ * @template GLOB - The glob pattern to match files against (defaults to '**\/*')
+ *
+ * @example
+ * ```typescript
+ * interface Props {
+ *   model: ProjectFile<'*.glb'>;           // Only .glb files
+ *   texture: ProjectFile<'*.{png,jpg}'>;   // PNG or JPG files
+ *   config: ProjectFile<'config/*.json'>;  // JSON files in config folder
+ *   any: ProjectFile;                      // Any file (defaults to '**\/*')
+ * }
+ * ```
+ */
+export type ProjectFile<GLOB extends string = '**/*'> = string;
+/**
+ * Represents a color value with specified format and color space.
+ *
+ * Colors default to unnormalized (0-255) range unless 'norm' is specified.
+ *
+ * @template FORMAT - The color format ('hex' | 'hexa' | 'rgb' | 'rgba' | 'norm-rgb' | 'norm-rgba' | 'css')
+ * @template SPACE - The color space ('srgb' | 'linear'), defaults to 'srgb'
+ *
+ * @example
+ * ```typescript
+ * interface Props {
+ *   background: Color<'hex'>;              // Hex color like "#FF0000"
+ *   tint: Color<'norm-rgb', 'linear'>;     // Normalized RGB [0,0,0] in linear space
+ *   overlay: Color<'rgba'>;                // RGBA array [255,0,0,255] (unnormalized default)
+ *   transparent: Color<'hexa'>;            // Hex with alpha "#FF0000FF"
+ *   material: Color<'norm-rgba'>;          // Normalized RGBA [1,0,0,1]
+ *   theme: Color<'css'>;                   // Any CSS color string
+ * }
+ * ```
+ */
+export type Color<FORMAT extends 'hex' | 'hexa' | 'rgb' | 'rgba' | 'norm-rgb' | 'norm-rgba' | 'css' = 'rgb', SPACE extends 'srgb' | 'linear' = 'srgb'> = FORMAT extends 'hex' | 'hexa' | 'css' ? string : FORMAT extends 'rgb' | 'norm-rgb' ? [
+    number,
+    number,
+    number
+] : FORMAT extends 'rgba' | 'norm-rgba' ? [
+    number,
+    number,
+    number,
+    number
+] : never;
+/**
+ * Represents a time duration with specified units.
+ *
+ * @template UNITS - The time units ('seconds' | 'milliseconds' | 'hertz')
+ *
+ * @example
+ * ```typescript
+ * interface Props {
+ *   duration: Time<'seconds'>;     // Duration in seconds
+ *   delay: Time<'milliseconds'>;   // Delay in milliseconds
+ *   frequency: Time<'hertz'>;      // Frequency in Hz
+ * }
+ * ```
+ */
+export type Time<UNITS extends 'seconds' | 'milliseconds' | 'hertz' = 'seconds'> = number;
+/**
+ * Represents a proportion value (0-1 range).
+ *
+ * @example
+ * ```typescript
+ * interface Props {
+ *   opacity: Proportion;    // 0-1 decimal value
+ *   progress: Proportion;   // 0-1 decimal value
+ * }
+ * ```
+ */
+export type Proportion = Range<0, 1>;
+/**
+ * The type system can validate URL format.
+ */
+export type Url = string;
+/**
+ * Represents multiline text content.
+ *
+ * @example
+ * ```typescript
+ * interface Props {
+ *   description: MultilineText;    // Renders as textarea
+ *   code: MultilineText;           // Multiline code input
+ * }
+ * ```
+ */
+export type MultilineText = string;
+/**
+ * Represents an email address with automatic validation.
+ *
+ * @example
+ * ```typescript
+ * interface Props {
+ *   contact: EmailAddress;         // Email input with validation
+ * }
+ * ```
+ */
+export type EmailAddress = string;

package/lib/types.js

@@ -20,6 +20,8 @@ export var TypeName;
     TypeName["Function"] = "function";
     TypeName["Event"] = "event";
     TypeName["Entity"] = "entity";
+    TypeName["ClassInstance"] = "classinstance";
+    TypeName["ConstructorForComponent"] = "constructorforcomponent";
 })(TypeName || (TypeName = {}));
 /**
  * Enumeration of type hints used to provide additional information about a type.
@@ -29,6 +31,7 @@ export var TypeName;
 export var TypeHint;
 (function (TypeHint) {
     TypeHint["proportion"] = "proportion";
+    TypeHint["range"] = "range";
     TypeHint["color-norm-rgb"] = "color-norm-rgb";
     TypeHint["color-norm-rgb-srgb"] = "color-norm-rgb-srgb";
     TypeHint["color-norm-rgb-linear"] = "color-norm-rgb-linear";
@@ -70,6 +73,7 @@ export var ValuesType;
     ValuesType["layerids"] = "layerids";
     ValuesType["streamids"] = "streamids";
     ValuesType["behaviorids"] = "behaviorids";
+    ValuesType["components"] = "components";
 })(ValuesType || (ValuesType = {}));
 /**
  * Checks if values in two objects are compatible.
@@ -102,6 +106,8 @@ export function areTypesCompatible(a, b) {
     if (a.name !== b.name)
         return false;
     switch (a.name) {
+        case 'classinstance':
+            return false;
         case 'array':
             return areTypesCompatible(a.child, b.child);
         case 'literal':
@@ -368,7 +374,7 @@ export function mergeTypes(a, b) {
                 ret: a.ret,
                 comments: mergeComments(a.comments ?? [], b.comments ?? []),
             };
-        case 'event':
+        case 'event': {
             const children = [];
             for (let i = 0; i < a.children.length; i++) {
                 const merged = mergeTypes(a.children[i], b.children[i]);
@@ -383,6 +389,12 @@ export function mergeTypes(a, b) {
                 comments: mergeComments(a.comments ?? [], b.comments ?? []),
                 names: mergeTupleNames(a, b),
             };
+        }
+        case 'classinstance':
+            return {
+                name: a.name,
+                comments: mergeComments(a.comments ?? [], b.comments ?? []),
+            };
     }
 }
 const regex = new RegExp(/((\.tsx?)|(\.d\.ts)|(\.jsx?))$/, 'i');
@@ -485,6 +497,12 @@ export function isValidValueForType(def, t, allowUndefined) {
                 return true;
             }
             return false;
+        case 'constructorforcomponent':
+            if (typeof def !== 'string')
+                return false;
+            if (!def.startsWith('import://'))
+                return false;
+            return true;
     }
     return false;
 }
@@ -510,6 +528,7 @@ function getBasicType(t) {
             }
             return `[${t.children.map(c => outputForType(c)).join(', ')}]`;
         case 'unknown':
+        case 'classinstance':
             return 'any';
         case 'number':
         case 'enum':
@@ -531,6 +550,8 @@ function getBasicType(t) {
                 return `Event<[${t.children.map((c, indx) => `${getSafeKeyName(t.names[indx])}: ${outputForType(c)}`).join(', ')}]>`;
             }
             return `Event<[${t.children.map(c => outputForType(c)).join(', ')}]>`;
+        case 'constructorforcomponent':
+            return 'ConstructorForComponent<any>';
     }
 }
 /**

package/lib/values/values.d.ts

@@ -1,11 +1,11 @@
-import { DeviceType } from '../profile';
+import { DeviceTypeValue } from '../profile';
 import type { Type } from '../types';
 export declare enum ConditionType {
-    'Locale' = "Locale",
-    'QueryString' = "Query String",
-    'UserAgent' = "User Agent",
-    'Debug' = "Debug",
-    'Default' = "Default"
+    Locale = "Locale",
+    QueryString = "Query String",
+    UserAgent = "User Agent",
+    Debug = "Debug",
+    Default = "Default"
 }
 export declare function getTypeForVariant(variant: ConditionType): Type;
 export interface BaseVariant {
@@ -27,7 +27,7 @@ export interface QueryStringVariant extends BaseVariant {
 }
 export interface UserAgentVariant extends BaseVariant {
     conditionType: ConditionType.UserAgent;
-    agent?: DeviceType;
+    agent?: DeviceTypeValue;
 }
 export interface DebugVariant extends BaseVariant {
     conditionType: ConditionType.Debug;
@@ -35,7 +35,6 @@ export interface DebugVariant extends BaseVariant {
 }
 export type ZVariant = LocaleVariant | QueryStringVariant | UserAgentVariant | DebugVariant | DefaultVariant;
 export declare class ValuesManager {
-    private valuesString;
     private profile;
     /**
      * Creates an instance of ValuesManager.

package/lib/values/values.js

@@ -30,6 +30,7 @@ export function getTypeForVariant(variant) {
     }
 }
 export class ValuesManager {
+    profile = new Profile();
     // TODO: Fix this any
     /**
      * Creates an instance of ValuesManager.
@@ -37,8 +38,6 @@ export class ValuesManager {
      * @param states - The states.
      */
     constructor(valuesString, states) {
-        this.valuesString = valuesString;
-        this.profile = new Profile();
         if (valuesString === undefined)
             throw new Error('Values are not defined');
         if (states === undefined)

package/lib/values/valuesmutator.d.ts

@@ -67,7 +67,10 @@ export declare function getTypesByKey(values: ZValues): Map<string, Type>;
  * @param values The values to check.
  * @returns Returns a map of key names to their [type representations, default values].
  */
-export declare function getTypesAndDefaultsByKey(values: ZValues): Map<string, [Type, any]>;
+export declare function getTypesAndDefaultsByKey(values: ZValues): Map<string, [
+    Type,
+    any
+]>;
 /**
  * Adds a new key to the values.
  * @param keyname The name of the key.

package/lib/values/valuesmutator.js

@@ -1,11 +1,9 @@
 import { ConditionType } from './values';
 export function changeKeyAndType(values, oldKeyName, newKeyName, type) {
-    if (!values.keys.hasOwnProperty(oldKeyName)) {
+    if (!Object.hasOwn(values.keys, oldKeyName))
         throw new Error(`The old key name '${oldKeyName}' does not exist in the 'keys' object.`);
-    }
-    if (values.keys.hasOwnProperty(newKeyName)) {
+    if (Object.hasOwn(values.keys, newKeyName))
         throw new Error(`The new key name '${newKeyName}' already exists in the 'keys' object.`);
-    }
     // Clone the old key and value properties
     values.keys[newKeyName] = JSON.parse(JSON.stringify(values.keys[oldKeyName]));
     values.values[newKeyName] = JSON.parse(JSON.stringify(values.values[oldKeyName]));
@@ -469,7 +467,7 @@ export function mergeCSVStringIntoTarget(csvString, currentValues) {
 function parseStringToVariant(str, priority) {
     const [param, ...value] = str.split(':');
     switch (param) {
-        case 'qs':
+        case 'qs': {
             const qsVariant = {
                 conditionType: ConditionType.QueryString,
                 param: value[0].split('=')[0],
@@ -477,27 +475,31 @@ function parseStringToVariant(str, priority) {
                 priority,
             };
             return qsVariant;
-        case 'ua':
+        }
+        case 'ua': {
             const uaVariant = {
                 conditionType: ConditionType.UserAgent,
                 agent: value[0],
                 priority,
             };
             return uaVariant;
-        case 'locale':
+        }
+        case 'locale': {
             const localeVariant = {
                 conditionType: ConditionType.Locale,
                 code: value[0],
                 priority,
             };
             return localeVariant;
-        case 'debug':
+        }
+        case 'debug': {
             const debugVariant = {
                 conditionType: ConditionType.Debug,
                 isEnabled: value[0] === 'true',
                 priority,
             };
             return debugVariant;
+        }
         case 'default': {
             const defaultVariant = {
                 conditionType: ConditionType.Default,

package/lib/zcomponent.d.ts

@@ -1,9 +1,9 @@
 import { Animation, Stream } from './animation/index';
 import { Behavior, ConstructorForBehavior } from './behavior';
 import { Component, ComponentChildren, ConstructorForComponent, ConstructorProps } from './component';
-import { ContextManager, Context } from './context';
-import { Entity } from './entity';
+import { Context, ContextManager } from './context';
 import { ZComponentData } from './data/core';
+import { Entity } from './entity';
 export interface ZComponentOptions {
     data: ZComponentData;
     importMapping: {
@@ -41,49 +41,59 @@ export declare class ZComponent<RootType = any> extends Component<RootType> {
     /**
      * The id of the component.
      */
-    id: string;
+    readonly id: string;
     /**
      * A map of elements to node IDs.
      */
-    idByElement: Map<any, string>;
+    readonly idByElement: Map<any, string>;
     /**
      * Object that maps node script names to scripts.
+     * @default {}
      */
-    nodes: {
+    readonly nodes: {
         [id: string]: Component | Component[];
     };
     /**
      * Map of entites  by ID.
      */
-    entityByID: Map<string, Entity>;
+    readonly entityByID: Map<string, Entity>;
     /**
      * A map of entity labels to components.
      */
-    entityByLabel: Map<string, Entity>;
+    readonly entityByLabel: Map<string, Entity>;
     /**
      * A map of node labels to components.
      */
-    nodeByLabel: Map<string, Component<any, ConstructorProps>>;
+    readonly nodeByLabel: Map<string, Component<any, ConstructorProps>>;
     private _constructedResolve;
     /**
      * A promise that is resolved once construction of this component is complete.
      */
     constructed: Promise<void>;
+    /**
+     * @default false
+     */
+    private _isConstructed;
     /**
      * A boolean indicating if construction of this component is complete.
      */
-    isConstructed: boolean;
+    get isConstructed(): boolean;
     /**
      * The animation object for this component.
+     * @zignore
      */
     animation: Animation;
     /**
      * @zstreams layerclipids
+     * @default {}
      */
-    streams: {
+    readonly streams: {
         [id: string]: Stream;
     };
     private _nodesById;
+    /**
+     * @default []
+     */
     private _behaviorsToInitialize;
     private _constructorPropOverridesByEntityID;
     /**
@@ -171,5 +181,6 @@ export declare class ZComponent<RootType = any> extends Component<RootType> {
     traverse(callback: (comp: Component<any>) => void, breadthFirst?: boolean): void;
     private _traverseBFS;
     private _traverseDFS;
+    private _constructTopLevelComponents;
     dispose(): never;
 }