cx 25.11.1 → 26.0.1

package/src/util/Component.spec.ts

@@ -0,0 +1,381 @@
+import assert from "assert";
+import { Component, ComponentConstructor, ComponentConfigType, ComponentInstanceType, Create, CreateConfig } from "./Component";
+
+// Test classes for type checking
+interface TestWidgetConfig {
+   text: string;
+   value?: number;
+}
+
+class TestWidget extends Component {
+   static isComponentType = true as const;
+   declare text?: string;
+   declare value?: number;
+
+   constructor(config?: TestWidgetConfig) {
+      super(config);
+   }
+}
+
+interface TestButtonConfig extends TestWidgetConfig {
+   onClick?: () => void;
+}
+
+class TestButton extends TestWidget {
+   declare onClick?: () => void;
+
+   constructor(config?: TestButtonConfig) {
+      super(config);
+   }
+}
+
+// Unrelated class (not in TestWidget hierarchy) for type testing
+interface UnrelatedConfig {
+   name: string;
+}
+
+class UnrelatedComponent extends Component {
+   declare name?: string;
+
+   constructor(config?: UnrelatedConfig) {
+      super(config);
+   }
+}
+
+// Register alias for testing
+Component.alias("test-widget", TestWidget);
+Component.alias("test-button", TestButton);
+
+describe("Component.create", function () {
+   describe("pass-through", function () {
+      it("returns the same instance if already a component", function () {
+         const btn = new TestButton({ text: "Hello" });
+         const result = Component.create(btn);
+         assert.strictEqual(result, btn);
+         assert.equal(result.text, "Hello");
+      });
+
+      it("preserves the component type", function () {
+         const btn = new TestButton({ text: "Hello" });
+         const result: TestButton = Component.create(btn);
+         assert.ok(result instanceof TestButton);
+      });
+   });
+
+   describe("array input", function () {
+      it("creates an array of components from array of configs", function () {
+         const results = TestWidget.create([{ text: "One" }, { text: "Two" }]);
+         assert.equal(results.length, 2);
+         assert.equal(results[0].text, "One");
+         assert.equal(results[1].text, "Two");
+      });
+
+      it("returns array of component instances", function () {
+         const configs = [{ text: "One" }];
+         const results = TestWidget.create(configs);
+         assert.ok(Array.isArray(results));
+         assert.ok(results[0] instanceof TestWidget);
+      });
+   });
+
+   describe("class type as first argument", function () {
+      it("creates instance of specified class", function () {
+         const result = Component.create(TestButton, { text: "Click me" });
+         assert.ok(result instanceof TestButton);
+         assert.equal(result.text, "Click me");
+      });
+
+      it("returns typed result based on class", function () {
+         const result: TestButton = Component.create(TestButton, { text: "Click" });
+         assert.ok(result instanceof TestButton);
+      });
+
+      it("merges config and more parameters", function () {
+         const result = Component.create(TestButton, { text: "Base" }, { value: 42 });
+         assert.equal(result.text, "Base");
+         assert.equal(result.value, 42);
+      });
+   });
+
+   describe("config with type property", function () {
+      it("creates instance of type specified in config", function () {
+         const result = Component.create({ type: TestButton, text: "Typed" });
+         assert.ok(result instanceof TestButton);
+         assert.equal(result.text, "Typed");
+      });
+
+      it("uses config properties for the created instance", function () {
+         const result = Component.create({
+            type: TestButton,
+            text: "Hello",
+            value: 123,
+         });
+         assert.equal(result.text, "Hello");
+         assert.equal(result.value, 123);
+      });
+   });
+
+   describe("config with $type property", function () {
+      it("creates instance of $type specified in config", function () {
+         const result = Component.create({ $type: TestButton, text: "Dollar" });
+         assert.ok(result instanceof TestButton);
+         assert.equal(result.text, "Dollar");
+      });
+   });
+
+   describe("class type with config and empty more object", function () {
+      it("creates instance with config and empty more object", function () {
+         const result = Component.create(TestWidget, { text: "Hello" }, {});
+         assert.ok(result instanceof TestWidget);
+         assert.equal(result.text, "Hello");
+      });
+   });
+
+   describe("parent class calling create with child class", function () {
+      it("creates child instance when called on parent class", function () {
+         // Pattern: ParentClass.create(ChildClass, config, more)
+         // This is how Widget.create(StaticText, { text }, {}) is used
+         const result = TestWidget.create(TestButton, { text: "Child" }, {});
+         assert.ok(result instanceof TestButton);
+         assert.equal(result.text, "Child");
+      });
+
+      it("returns properly typed child instance", function () {
+         const result: TestButton = TestWidget.create(TestButton, { text: "Typed" });
+         assert.ok(result instanceof TestButton);
+      });
+   });
+
+   describe("string alias", function () {
+      it("creates instance from registered alias", function () {
+         const result = Component.create("test-button", { text: "Aliased" });
+         assert.ok(result instanceof TestButton);
+         assert.equal(result.text, "Aliased");
+      });
+
+      it("throws for unknown alias", function () {
+         assert.throws(() => {
+            Component.create("unknown-alias");
+         }, /Unknown component alias/);
+      });
+   });
+
+   describe("plain config object", function () {
+      it("creates instance of the class create is called on", function () {
+         const result = TestWidget.create({ text: "Plain" });
+         assert.ok(result instanceof TestWidget);
+         assert.equal(result.text, "Plain");
+      });
+
+      it("works with subclasses", function () {
+         const result = TestButton.create({ text: "Sub", onClick: () => {} });
+         assert.ok(result instanceof TestButton);
+         assert.equal(result.text, "Sub");
+      });
+   });
+
+   describe("config array as second argument", function () {
+      it("creates array when config is an array", function () {
+         const results = Component.create(TestWidget, [{ text: "A" }, { text: "B" }]);
+         assert.equal(results.length, 2);
+         assert.ok(results[0] instanceof TestWidget);
+         assert.ok(results[1] instanceof TestWidget);
+      });
+   });
+
+   describe("type inference", function () {
+      it("infers config type from class constructor", function () {
+         // This is a compile-time check - if it compiles, the types are correct
+         const config: ComponentConfigType<typeof TestButton> = {
+            text: "Hello",
+            onClick: () => {},
+         };
+         const result = Component.create(TestButton, config);
+         assert.ok(result instanceof TestButton);
+      });
+   });
+
+   describe("config with type and more argument", function () {
+      it("merges config and more parameters", function () {
+         const result = Component.create({ type: TestButton, text: "Base" }, { value: 42 });
+         assert.ok(result instanceof TestButton);
+         assert.equal(result.text, "Base");
+         assert.equal(result.value, 42);
+      });
+
+      it("works with $type as well", function () {
+         const result = Component.create({ $type: TestButton, text: "Dollar" }, { value: 99 });
+         assert.ok(result instanceof TestButton);
+         assert.equal(result.text, "Dollar");
+         assert.equal(result.value, 99);
+      });
+   });
+
+   describe("heterogeneous array with type property", function () {
+      it("creates array of different component types", function () {
+         const results = Component.create([
+            { type: TestWidget, text: "Widget" },
+            { type: TestButton, text: "Button", onClick: () => {} },
+         ]);
+         assert.equal(results.length, 2);
+         assert.ok(results[0] instanceof TestWidget);
+         assert.ok(results[1] instanceof TestButton);
+         assert.equal(results[0].text, "Widget");
+         assert.equal(results[1].text, "Button");
+      });
+
+      it("returns properly typed tuple", function () {
+         const results = Component.create([
+            { type: TestWidget, text: "W" },
+            { type: TestButton, text: "B" },
+         ]);
+         // Type check: results[0] should be TestWidget, results[1] should be TestButton
+         const widget: TestWidget = results[0];
+         const button: TestButton = results[1];
+         assert.ok(widget instanceof TestWidget);
+         assert.ok(button instanceof TestButton);
+      });
+   });
+
+   describe("this-bound create with config", function () {
+      it("creates instance when called on specific class", function () {
+         const result = TestButton.create({ text: "Bound", onClick: () => {} });
+         assert.ok(result instanceof TestButton);
+         assert.equal(result.text, "Bound");
+      });
+
+      it("accepts more parameter for additional config", function () {
+         const result = TestButton.create({ text: "Main" }, { value: 100 });
+         assert.ok(result instanceof TestButton);
+         assert.equal(result.text, "Main");
+         assert.equal(result.value, 100);
+      });
+   });
+
+   describe("this-bound create with array", function () {
+      it("creates array of instances when called on specific class", function () {
+         const results = TestButton.create([{ text: "A" }, { text: "B" }]);
+         assert.equal(results.length, 2);
+         assert.ok(results[0] instanceof TestButton);
+         assert.ok(results[1] instanceof TestButton);
+      });
+
+      it("accepts more parameter for array", function () {
+         const results = TestButton.create([{ text: "X" }, { text: "Y" }], { value: 50 });
+         assert.equal(results.length, 2);
+         assert.equal(results[0].value, 50);
+         assert.equal(results[1].value, 50);
+      });
+   });
+});
+
+describe("Create type", function () {
+   // Helper function that accepts Create
+   function createComponent<TCtor extends ComponentConstructor>(
+      creatable: Create<TCtor>,
+   ): ComponentInstanceType<TCtor> {
+      return Component.create(creatable as any);
+   }
+
+   it("accepts instance pass-through", function () {
+      const widget = new TestWidget({ text: "Instance" });
+      const result = createComponent<typeof TestWidget>(widget);
+      assert.strictEqual(result, widget);
+   });
+
+   it("accepts constructor", function () {
+      const result = createComponent<typeof TestWidget>(TestButton);
+      assert.ok(result instanceof TestButton);
+   });
+
+   it("accepts config with type", function () {
+      const result = createComponent<typeof TestWidget>({ type: TestButton, text: "Typed" });
+      assert.ok(result instanceof TestButton);
+      assert.equal(result.text, "Typed");
+   });
+
+   it("accepts config with $type", function () {
+      const result = createComponent<typeof TestWidget>({ $type: TestButton, text: "DollarTyped" });
+      assert.ok(result instanceof TestButton);
+      assert.equal(result.text, "DollarTyped");
+   });
+});
+
+describe("CreateConfig type safety", function () {
+   it("rejects config with type from unrelated class", function () {
+      // @ts-expect-error - UnrelatedComponent is not a subclass of TestWidget
+      const config: CreateConfig<typeof TestWidget> = { type: UnrelatedComponent, name: "test" };
+   });
+
+   it("rejects config missing required properties", function () {
+      // @ts-expect-error - text is required in TestWidgetConfig
+      const config: CreateConfig<typeof TestWidget> = { type: TestButton };
+   });
+
+   it("accepts config with type from subclass and required properties", function () {
+      const config: CreateConfig<typeof TestWidget> = { type: TestButton, text: "valid" };
+      assert.ok(config);
+   });
+
+   it("accepts constructor from subclass", function () {
+      const config: CreateConfig<typeof TestWidget> = TestButton;
+      assert.ok(config);
+   });
+});
+
+describe("Create type as property (like Chart.axes)", function () {
+   // Simulates how Chart uses Create<typeof Axis> for its axes property
+   interface ContainerConfig {
+      items?: Record<string, Create<typeof TestWidget>>;
+   }
+
+   it("accepts constructor as property value", function () {
+      const config: ContainerConfig = {
+         items: {
+            a: TestWidget,
+            b: TestButton,
+         },
+      };
+      assert.ok(config);
+   });
+
+   it("accepts config with type as property value", function () {
+      const config: ContainerConfig = {
+         items: {
+            a: { type: TestWidget, text: "widget" },
+            b: { type: TestButton, text: "button", onClick: () => {} },
+         },
+      };
+      assert.ok(config);
+   });
+
+   it("accepts config with $type as property value", function () {
+      const config: ContainerConfig = {
+         items: {
+            a: { $type: TestWidget, text: "widget" },
+            b: { $type: TestButton, text: "button" },
+         },
+      };
+      assert.ok(config);
+   });
+
+   it("accepts instance as property value", function () {
+      const config: ContainerConfig = {
+         items: {
+            a: new TestWidget({ text: "instance" }),
+            b: new TestButton({ text: "button" }),
+         },
+      };
+      assert.ok(config);
+   });
+
+   it("accepts config with extra properties", function () {
+      const config: ContainerConfig = {
+         items: {
+            // Extra property (like snapToTicks on NumericAxis)
+            a: { type: TestButton, text: "button", onClick: () => {}, value: 42 },
+         },
+      };
+      assert.ok(config);
+   });
+});

package/src/util/Component.ts

@@ -0,0 +1,296 @@
+import { isString } from "./isString";
+import { isFunction } from "./isFunction";
+import { isArray } from "./isArray";
+
+interface DecoratorFactory<T> {
+   (t: T): T;
+}
+
+/** A Component class constructor (supports abstract classes) */
+export type ComponentConstructor<T extends Component = Component> = (abstract new (config?: any) => T) & {
+   isComponentType: true;
+   prototype: T;
+};
+
+/** Extract the config type from a Component class constructor */
+export type ComponentConfigType<T> = T extends abstract new (config?: infer C) => any
+   ? C & { isComponentType?: never }
+   : unknown;
+
+/** Extract the instance type from a Component class constructor */
+export type ComponentInstanceType<T> = T extends abstract new (config?: any) => infer I ? I : Component;
+
+/**
+ * Type representing any valid input to Component.create that will produce an instance of T.
+ *
+ * Accepts:
+ * - An instance of T (pass-through)
+ * - A constructor for T or any subtype
+ * - A config object for T (when T has a known config type)
+ * - A config object with `type` or `$type` property specifying the constructor
+ *
+ * @example
+ * // In a Chart widget config:
+ * interface ChartConfig {
+ *    xAxis?: Creatable<Axis>;  // Accepts NumericAxis, CategoryAxis, etc.
+ *    yAxis?: Creatable<Axis>;
+ * }
+ *
+ * // Usage:
+ * <Chart xAxis={NumericAxis} />  // Just the type
+ * <Chart xAxis={{ type: NumericAxis, min: 0, max: 100 }} />  // Config with type
+ * <Chart xAxis={new NumericAxis({ min: 0 })} />  // Instance
+ */
+
+// Helper type: constructor for T or any subclass
+type SubclassConstructor<TBaseCtor extends ComponentConstructor> = ComponentConstructor<
+   ComponentInstanceType<TBaseCtor>
+>;
+
+// Helper: get config type, falling back to base if subclass config is `any`
+type ResolveConfigType<TBaseCtor extends ComponentConstructor, TSubCtor extends ComponentConstructor> = 0 extends 1 &
+   ComponentConfigType<TSubCtor>
+   ? ComponentConfigType<TBaseCtor> // TSubCtor config is `any`, use base config
+   : ComponentConfigType<TSubCtor>; // Use specific subclass config
+
+// Config with type property - uses inference to capture the actual subclass constructor
+// When a specific subclass is provided, its config is used; otherwise base config + extra props allowed
+type ConfigWithType<TBaseCtor extends ComponentConstructor, TSubCtor extends SubclassConstructor<TBaseCtor>> = {
+   type: TSubCtor;
+} & ResolveConfigType<TBaseCtor, TSubCtor> &
+   // Allow extra properties when using generic subclass (enables subclass-specific props)
+   (0 extends 1 & ComponentConfigType<TSubCtor> ? { [key: string]: unknown } : {});
+
+type ConfigWith$Type<TBaseCtor extends ComponentConstructor, TSubCtor extends SubclassConstructor<TBaseCtor>> = {
+   $type: TSubCtor;
+} & ResolveConfigType<TBaseCtor, TSubCtor> &
+   // Allow extra properties when using generic subclass (enables subclass-specific props)
+   (0 extends 1 & ComponentConfigType<TSubCtor> ? { [key: string]: unknown } : {});
+
+export type CreateConfig<
+   TBaseCtor extends ComponentConstructor,
+   TSubCtor extends SubclassConstructor<TBaseCtor> = SubclassConstructor<TBaseCtor>,
+> =
+   | TSubCtor // Constructor for T or subclass
+   | ConfigWithType<TBaseCtor, TSubCtor> // Config object with type
+   | ConfigWith$Type<TBaseCtor, TSubCtor>; // Config object with $type
+
+export type Create<TCtor extends ComponentConstructor> =
+   | ComponentInstanceType<TCtor> // Instance pass-through
+   | CreateConfig<TCtor>;
+
+/**
+ * Type-checks a CreateConfig object based on its `type` or `$type` property.
+ * This is a compile-time helper that returns the input unchanged at runtime.
+ * Uses `const` type parameter (TypeScript 5.0+) to enable excess property checking.
+ *
+ * @example
+ * // With type property
+ * const axisConfig = validateConfig({ type: NumericAxis, min: 0, max: 100 });
+ *
+ * // With $type property
+ * const selectionConfig = validateConfig({ $type: KeySelection, bind: "selection" });
+ */
+export function validateConfig<const TCtor extends ComponentConstructor>(
+   config:
+      | ({ type: TCtor; $type?: never } & ComponentConfigType<TCtor>)
+      | ({ $type: TCtor; type?: never } & ComponentConfigType<TCtor>),
+): any {
+   return config;
+}
+
+const componentAlias: Record<string, any> = {};
+
+export class Component {
+   public static namespace: string;
+   public static isComponentType: true;
+   public static autoInit: boolean;
+   public static factory: (alias: string, config?: any, more?: any) => Component;
+   declare public isComponent: boolean;
+
+   constructor(config?: any) {
+      if (config && config.$props) {
+         Object.assign(config, config.$props);
+         delete config.$props;
+      }
+      Object.assign(this, config);
+   }
+
+   init() {}
+
+   /**
+    *
+    * @param alias
+    * @param type
+    */
+   static alias<T>(alias: string, type: T): void;
+   static alias<T>(alias: string): DecoratorFactory<T>;
+   static alias(alias: string, type?: any) {
+      if (type) {
+         type.prototype.componentAlias = alias;
+         componentAlias[this.namespace + alias] = type;
+      } //decorator usage
+      else
+         return (t: any) => {
+            this.alias(alias, t);
+            return t;
+         };
+   }
+
+   /**
+    * Creates a component instance from various input types.
+    *
+    * Supported signatures:
+    * - Pass-through: If input is already a component instance, returns it unchanged
+    * - Array: Maps over array elements, creating components for each
+    * - Class type: Creates instance of the specified class with config
+    * - Config with type/$type: Creates instance of the type specified in config
+    * - String alias: Looks up registered alias and creates that type
+    * - Plain config: Creates instance of the class `create` was called on
+    *
+    * @example
+    * // Pass-through
+    * const btn = new Button();
+    * Button.create(btn) // returns btn as Button
+    *
+    * // Class type with config
+    * Button.create(Button, { text: "Click" }) // returns Button
+    *
+    * // Config with type property
+    * Widget.create({ type: Button, text: "Click" }) // returns Button
+    *
+    * // Plain config on specific class
+    * Button.create({ text: "Click" }) // returns Button with ButtonConfig typing
+    */
+
+   // Pass-through: already a component instance
+   static create<T extends Component>(instance: T, unused?: any): T;
+
+   // Array of config objects with type or $type property (each item can have different type)
+   static create<
+      T extends ({ type: ComponentConstructor; $type?: never } | { $type: ComponentConstructor; type?: never })[],
+   >(
+      configs: [...T],
+      more?: Record<string, any>,
+   ): {
+      [K in keyof T]: T[K] extends { type: ComponentConstructor<infer U> }
+         ? U
+         : T[K] extends { $type: ComponentConstructor<infer U> }
+           ? U
+           : Component;
+   };
+
+   // Config object with type or $type property
+   static create<TCtor extends ComponentConstructor, T extends Component = ComponentInstanceType<TCtor>>(
+      config: (
+         | { type: TCtor; $type?: never; isComponentType?: never }
+         | { $type: TCtor; type?: never; isComponentType?: never }
+      ) &
+         Partial<ComponentConfigType<ComponentConstructor<T>>>,
+      more?: Partial<ComponentConfigType<ComponentConstructor<T>>>,
+   ): T;
+
+   // Class type with array of configs - returns array of instances
+   static create<TCtor extends ComponentConstructor, T extends Component = ComponentInstanceType<TCtor>>(
+      type: TCtor,
+      configs: ComponentConfigType<ComponentConstructor<T>>[],
+      more?: Partial<ComponentConfigType<ComponentConstructor<T>>>,
+   ): T[];
+
+   // Explicit class type as first argument with typed config
+   static create<TCtor extends ComponentConstructor, T extends Component = ComponentInstanceType<TCtor>>(
+      type: TCtor,
+      config?: ComponentConfigType<ComponentConstructor<T>>,
+      more?: Partial<ComponentConfigType<ComponentConstructor<T>>>,
+   ): T;
+
+   // Array of configs - returns array of instances of this class (this-bound)
+   static create<T extends Component>(
+      this: { prototype: T; isComponentType: true },
+      configs: ComponentConfigType<ComponentConstructor<T>>[],
+      more?: Partial<ComponentConfigType<ComponentConstructor<T>>>,
+   ): T[];
+
+   // Config object - returns instance of this class (this-bound)
+   static create<T extends Component>(
+      this: { prototype: T; isComponentType: true },
+      config: ComponentConfigType<ComponentConstructor<T>>,
+      more?: Partial<ComponentConfigType<ComponentConstructor<T>>>,
+   ): T;
+
+   // String alias (e.g., "div", "button") - returns instance of this class
+   static create<T extends Component>(
+      this: { prototype: T; isComponentType: true },
+      alias: string,
+      config?: ComponentConfigType<ComponentConstructor<T>>,
+      more?: Partial<ComponentConfigType<ComponentConstructor<T>>>,
+   ): T;
+
+   // Implementation
+   static create(typeAlias?: any, config?: any, more?: any): any {
+      if (!typeAlias) return this.factory(typeAlias, config, more);
+
+      if (typeAlias.isComponent) return typeAlias;
+
+      if (isComponentFactory(typeAlias)) return this.create(typeAlias.create(config), config, more);
+
+      if (isArray(typeAlias)) return typeAlias.map((c) => this.create(c as any, config, more));
+
+      if (typeAlias.$type) return this.create(typeAlias.$type, typeAlias, config);
+
+      if (typeAlias.type) return this.create(typeAlias.type, typeAlias, config);
+
+      let cmpType: any, alias: string;
+
+      if (typeAlias.isComponentType) cmpType = typeAlias;
+      else if (isFunction(typeAlias)) {
+         if (this.factory) return this.factory(typeAlias, config, more);
+         throw new Error(`Unsupported component type ${typeAlias}.`);
+      } else if (isString(typeAlias)) {
+         alias = this.namespace + typeAlias;
+         cmpType = componentAlias[alias];
+         if (!cmpType) {
+            if (typeAlias && this.factory) return this.factory(typeAlias, config, more);
+            throw new Error(`Unknown component alias ${alias}.`);
+         }
+      } else if (typeof typeAlias == "object") {
+         cmpType = typeAlias.type || typeAlias.$type;
+         if (!cmpType) {
+            cmpType = this;
+            more = more ? Object.assign({}, config, more) : config;
+            config = typeAlias;
+         }
+      }
+
+      if (isArray(config)) return config.map((cfg: any) => this.create(cmpType, cfg, more));
+
+      let cfg = config;
+
+      if (more) cfg = Object.assign({}, config, more);
+
+      let cmp = new cmpType(cfg);
+      if (cmpType.autoInit && cmp.init) cmp.init();
+      return cmp;
+   }
+}
+
+Component.prototype.isComponent = true;
+
+Component.isComponentType = true;
+Component.namespace = "";
+Component.autoInit = false;
+
+Component.factory = (alias: string, _config?: any, _more?: any): Component => {
+   throw new Error(`Unknown component alias ${alias}.`);
+};
+
+export function createComponentFactory(factory: any, jsxDriver: any, meta?: any) {
+   factory.$isComponentFactory = true;
+   factory.$meta = meta;
+   factory.create = jsxDriver;
+   return factory;
+}
+
+export function isComponentFactory(factory: any): boolean {
+   return factory && factory.$isComponentFactory;
+}

package/src/util/Console.ts

@@ -0,0 +1,11 @@
+export const Console = {
+   log: (...args: any[]): void => {
+      if (typeof window != 'undefined' && window.console)
+         console.log(...args);
+   },
+
+   warn: (...args: any[]): void => {
+      if (typeof window != 'undefined' && window.console)
+         console.warn(...args);
+   }
+};