cx 25.10.1 → 26.0.1

package/src/ui/VDOM.ts

@@ -0,0 +1,34 @@
+// @ts-expect-error
+import { VDOM as vdom } from "cx-react";
+
+import type * as React from "react";
+import type { Component } from "react";
+import type {
+   unstable_batchedUpdates,
+   render,
+   findDOMNode,
+   createPortal,
+   unstable_renderSubtreeIntoContainer,
+   hydrate,
+   unmountComponentAtNode,
+} from "react-dom";
+import type { createRoot, hydrateRoot, Root } from "react-dom/client";
+
+export interface VDOMType extends Omit<typeof React, "default"> {
+   allowRenderOutputCaching?: boolean;
+   Component: typeof Component;
+
+   DOM: {
+      unstable_batchedUpdates: typeof unstable_batchedUpdates;
+      render: typeof render;
+      findDOMNode: typeof findDOMNode;
+      createPortal: typeof createPortal;
+      createRoot: typeof createRoot;
+      hydrateRoot: typeof hydrateRoot;
+      hydrate: typeof hydrate;
+      unmountComponentAtNode: typeof unmountComponentAtNode;
+      unstable_renderSubtreeIntoContainer: typeof unstable_renderSubtreeIntoContainer;
+   };
+}
+
+export const VDOM = vdom as VDOMType;

package/src/ui/Widget.spec.tsx

@@ -0,0 +1,53 @@
+import { Controller, ControllerConfig } from "./Controller";
+import { ControllerProp } from "./Widget";
+import { validateConfig } from "../util/Component";
+import assert from "assert";
+
+describe("ControllerProp type safety", () => {
+   interface RequiredPropControllerConfig extends ControllerConfig {
+      multiplier: number;
+   }
+
+   class RequiredPropController extends Controller {
+      constructor(config?: RequiredPropControllerConfig) {
+         super(config);
+      }
+   }
+
+   interface StrictControllerConfig extends ControllerConfig {
+      validProp: number;
+   }
+
+   class StrictController extends Controller {
+      constructor(config?: StrictControllerConfig) {
+         super(config);
+      }
+   }
+
+   it.skip("rejects CreateConfig missing required properties", () => {
+      // @ts-expect-error - multiplier is required
+      const controller: ControllerProp = validateConfig({
+         type: RequiredPropController,
+      });
+      assert.ok(controller);
+   });
+
+   it("rejects CreateConfig with non-existing properties", () => {
+      const controller: ControllerProp = validateConfig({
+         type: StrictController,
+         validProp: 1,
+         // @ts-expect-error - nonExistingProp does not exist
+         nonExistingProp: "invalid",
+      });
+      assert.ok(controller);
+   });
+
+   it("rejects CreateConfig with wrong property type", () => {
+      const controller: ControllerProp = validateConfig({
+         type: StrictController,
+         // @ts-expect-error - validProp should be number, not string
+         validProp: "wrong type",
+      });
+      assert.ok(controller);
+   });
+});

package/src/ui/Widget.tsx

@@ -0,0 +1,308 @@
+import { StructuredSelector } from "../data/StructuredSelector";
+import { Component, CreateConfig } from "../util/Component";
+import { Console } from "../util/Console";
+import { isArray } from "../util/isArray";
+import { isDefined } from "../util/isDefined";
+import { isString } from "../util/isString";
+import { parseStyle } from "../util/parseStyle";
+import { CSS } from "./CSS";
+import { CSSHelper } from "./CSSHelper";
+import { RenderingContext } from "./RenderingContext";
+import type { Controller, ControllerConfig, ControllerFactory } from "./Controller";
+
+import { BooleanProp, ClassProp, ModProp, StyleProp } from "./Prop";
+import { Instance } from "./Instance";
+import { VDOM as vdom } from "./VDOM";
+
+export const VDOM = vdom;
+
+let widgetId = 100;
+
+// Controller property accepts: class, config object with type/$type, inline config, or factory function
+// ControllerConfig is intersected with { type?: never; $type?: never } to ensure objects with type/$type match CreateConfig
+export type ControllerProp =
+   | CreateConfig<typeof Controller>
+   | (ControllerConfig & { type?: never; $type?: never })
+   | ControllerFactory;
+
+export interface WidgetConfig {
+   /** Visibility of the widget. Defaults to `true`. */
+   visible?: BooleanProp;
+
+   /** Visibility of the widget. Defaults to `true`. */
+   if?: BooleanProp;
+
+   /** Outer (wrapper) layout used to display the widget in. */
+   outerLayout?: unknown;
+
+   /** Inner layout used to display children inside the widget. */
+   layout?: unknown;
+
+   /** Name of the ContentPlaceholder that should be used to display the widget. */
+   contentFor?: string;
+
+   /** Name of the ContentPlaceholder that should be used to display the widget. */
+   putInto?: string;
+
+   /** Key that will be used as the key when rendering the React component.  */
+   vdomKey?: string;
+
+   /** Controller. */
+   controller?: ControllerProp;
+
+   onInit?(context: RenderingContext): void;
+   onExplore?(context: RenderingContext, instance: Instance): void;
+   onPrepare?(context: RenderingContext, instance: Instance): void;
+   onCleanup?(context: RenderingContext, instance: Instance): void;
+   onDestroy?(instance: Instance): void;
+}
+
+/** Style-related config properties for widgets that support styling. */
+export interface WidgetStyleConfig {
+   /**
+    * Additional CSS classes to be applied to the element.
+    * If an object is provided, all keys with a "truthy" value will be added to the CSS class list.
+    */
+   class?: ClassProp;
+
+   /**
+    * Additional CSS classes to be applied to the element.
+    * If an object is provided, all keys with a "truthy" value will be added to the CSS class list.
+    */
+   className?: ClassProp;
+
+   /** Style object applied to the element. */
+   style?: StyleProp;
+
+   /** Style object applied to the element. */
+   styles?: StyleProp;
+
+   /** Base CSS class to be applied to the element. For example, value 'button' will add a class 'cxb-button' to the element. */
+   baseClass?: string;
+
+   /** Appearance modifier. For example, mod="big" will add the CSS class .cxm-big to the block element. */
+   mod?: ModProp;
+}
+
+export abstract class Widget<
+   Config extends WidgetConfig = WidgetConfig,
+   InstanceType extends Instance = Instance,
+> extends Component {
+   // config props
+   declare public vdomKey?: string | number;
+   declare public jsxSpread?: Record<string, any>[];
+   declare public jsxAttributes?: string[];
+   declare public styles?: any;
+   declare public style?: any;
+   declare public styled: boolean;
+   declare public if?: any;
+   declare public visible: boolean;
+   declare public outerLayout?: Widget;
+   declare public contentFor?: string;
+   declare public putInto?: string;
+   declare public isContent?: boolean;
+   declare public CSS: typeof CSS;
+   declare public baseClass?: string;
+   declare public memoize: boolean;
+   declare public controller?: Controller;
+   declare public isPureContainer?: boolean;
+   declare public useParentLayout?: boolean;
+
+   // runtime values
+   public widgetId?: number;
+   public initialized?: boolean;
+   public components?: Record<string, any>;
+   public helpers?: Record<string, any>;
+   public selector?: StructuredSelector;
+   public nameMap?: any;
+   public version?: number;
+
+   // Lifecycle hooks - callbacks that can be set in configuration
+   declare public onInit?: (context: RenderingContext, instance: Instance) => void;
+   declare public onExplore?: (context: RenderingContext, instance: Instance) => void;
+   declare public onPrepare?: (context: RenderingContext, instance: Instance) => void;
+   declare public onCleanup?: (context: RenderingContext, instance: Instance) => void;
+   declare public onDestroy?: (instance: Instance) => void;
+
+   // Lifecycle methods that can be overridden by subclasses
+   public exploreCleanup?(context: RenderingContext, instance: InstanceType): void;
+   public prepareCleanup?(context: RenderingContext, instance: InstanceType): void;
+   public cleanup?(context: RenderingContext, instance: InstanceType): void;
+   public prepare?(context: RenderingContext, instance: InstanceType): void;
+
+   public static optimizePrepare?: boolean;
+
+   constructor(config?: Config) {
+      super(config);
+      this.widgetId = widgetId++;
+
+      if (isArray(this.jsxSpread)) {
+         if (!this.jsxAttributes) this.jsxAttributes = [];
+
+         this.jsxSpread.forEach((spread: Record<string, any>) => {
+            for (const key in spread) {
+               (this as any)[key] = spread[key];
+               this.jsxAttributes!.push(key);
+            }
+         });
+      }
+   }
+
+   public init(): void {
+      if (this.styles) this.style = this.styles;
+
+      if (this.styled) this.style = parseStyle(this.style);
+      else if (this.style) {
+         Console.warn(
+            "Components that allow use of the style attribute should set styled = true on their prototype. This will be an error in future versions.",
+         );
+         this.style = parseStyle(this.style);
+         this.styled = true;
+      }
+
+      if (typeof this.if !== "undefined") this.visible = this.if;
+
+      this.declareData();
+
+      if (this.outerLayout) {
+         if (isArray(this.outerLayout)) throw new Error("Only single element outer layout is supported.");
+         //TODO: better handle the case when outer layout is an array. How to get around circular dependency to PureContainer
+         this.outerLayout = Widget.create(this.outerLayout, {});
+      }
+
+      if (this.contentFor) this.putInto = this.contentFor;
+
+      if (this.putInto) this.isContent = true;
+
+      if (isString(this.CSS)) this.CSS = CSSHelper.get(this.CSS);
+
+      this.initHelpers();
+      this.initComponents();
+
+      this.initialized = true;
+   }
+
+   protected initComponents(...args: Record<string, any>[]): void {
+      if (args.length > 0) {
+         this.components = Object.assign({}, ...args);
+         for (const k in this.components) {
+            if (!this.components[k]) delete this.components[k];
+         }
+      }
+   }
+
+   protected initHelpers(...args: Record<string, any>[]): void {
+      if (args.length > 0) {
+         this.helpers = Object.assign({}, ...args);
+      }
+   }
+
+   protected declareData(...args: Record<string, any>[]): void {
+      const options: Record<string, any> = {};
+
+      if (this.styled) {
+         options.class = options.className = options.style = { structured: true };
+      }
+
+      const props = {
+         visible: undefined,
+         mod: {
+            structured: true,
+         },
+         ...options,
+      };
+
+      Object.assign(props, ...args);
+      this.selector = new StructuredSelector({ props: props, values: this });
+      this.nameMap = this.selector.nameMap;
+   }
+
+   protected prepareCSS(_context: RenderingContext, { data }: any): void {
+      data.classNames = this.CSS.expand(
+         this.CSS.block(this.baseClass!, data.mod, data.stateMods),
+         data.class,
+         data.className,
+      );
+      data.style = parseStyle(data.style);
+   }
+
+   public prepareData(context: RenderingContext, instance: InstanceType): void {
+      if (this.styled) this.prepareCSS(context, instance);
+   }
+
+   public initInstance(_context: RenderingContext, _instance: InstanceType): void {}
+
+   public initState(_context: RenderingContext, _instance: InstanceType): void {}
+
+   public checkVisible(_context: RenderingContext, _instance: InstanceType, data: any): boolean {
+      return data.visible;
+   }
+
+   public explore(context: RenderingContext, instance: InstanceType, data?: any): void {
+      if (this.components) {
+         instance.components = {};
+         for (const cmp in this.components) {
+            const ins = instance.getChild(context, this.components[cmp], "cmp-" + cmp, instance.store);
+            if (ins.scheduleExploreIfVisible(context)) instance.components[cmp] = ins;
+         }
+      }
+   }
+
+   public render(context: RenderingContext, instance: InstanceType, key: string): any {
+      Console.log(this);
+      throw new Error(
+         'Widget\'s render method should be overridden. This error usually happens if with incorrect imports, i.e. import { TextField } from "cx/data". Please check the console for details about the component configuration.',
+      );
+   }
+
+   public update(): void {
+      this.version = (this.version || 0) + 1;
+   }
+
+   public applyParentStore(instance: any): void {
+      instance.store = instance.parentStore;
+
+      // check when this is actually needed, perhaps this is needed only for tables and repeated elements
+      // if (instance.cached) delete instance.cached.rawData; // force prepareData to execute again
+   }
+
+   public static resetCounter(): void {
+      widgetId = 100;
+   }
+}
+
+Widget.prototype.visible = true;
+Widget.prototype.memoize = true; //cache rendered content and use it if possible
+Widget.prototype.CSS = CSS;
+Widget.prototype.styled = false;
+
+Widget.namespace = "ui.";
+Widget.optimizePrepare = true;
+
+Widget.factory = (type: string, _config?: any, _more?: any) => {
+   throw new Error(`Invalid widget type: ${type}.`);
+};
+
+export function contentAppend(result: any[], w: any, prependSpace?: boolean): boolean {
+   if (w == null || w === false) return false;
+   if (isArray(w)) w.forEach((c: any) => contentAppend(result, c));
+   else if (isDefined(w.content) && !w.atomic) return contentAppend(result, w.content, false);
+   else {
+      if (prependSpace) result.push(" ");
+      result.push(w);
+   }
+   return true;
+}
+
+export function getContentArray(x: any): any[] {
+   let result: any[] = [];
+   contentAppend(result, x, false);
+   return result;
+}
+
+export function getContent(x: any): any {
+   let result = getContentArray(x);
+   if (result.length == 0) return null;
+   if (result.length == 1) return result[0];
+   return result;
+}

package/src/ui/ZIndexManager.ts

@@ -0,0 +1,11 @@
+let lastZIndex = 10000;
+
+export class ZIndexManager {
+   static next() {
+      return ++lastZIndex;
+   }
+
+   static reset(zIndex: number) {
+      lastZIndex = zIndex;
+   }
+}

package/src/ui/adapter/ArrayAdapter.spec.ts

@@ -0,0 +1,55 @@
+import { RenderingContext } from "../RenderingContext";
+import { Instance } from "../Instance";
+import { TreeAdapter } from "./TreeAdapter";
+import assert from "assert";
+import { Store } from "../../data";
+import { ArrayAdapter } from "./ArrayAdapter";
+
+describe("ArrayAdapter", () => {
+   it("maps data into records", () => {
+      let adapter = new ArrayAdapter();
+      let data = [
+         {
+            id: 1,
+            text: "1",
+         },
+         {
+            id: 2,
+            text: "2",
+         },
+      ];
+
+      let store = new Store();
+
+      let records = adapter.mapRecords(new RenderingContext(), new Instance(null!, "1", null!, store), data, store);
+
+      assert.equal(records.length, 2);
+      assert.equal(records[0].data, records[0].store.get("$record"));
+      assert.equal(records[1].data, records[1].store.get("$record"));
+   });
+
+   it("can sort data", () => {
+      let adapter = new ArrayAdapter();
+
+      adapter.sort([{ field: "id", direction: "DESC" }]);
+
+      let data = [
+         {
+            id: 1,
+            text: "1",
+         },
+         {
+            id: 2,
+            text: "2",
+         },
+      ];
+
+      let store = new Store();
+
+      let records = adapter.mapRecords(new RenderingContext(), new Instance(null!, "1", null!, store), data, store);
+
+      assert.equal(records.length, 2);
+      assert.equal(data[1], records[0].store.get("$record"));
+      assert.equal(data[0], records[1].store.get("$record"));
+   });
+});

package/src/ui/adapter/ArrayAdapter.ts

@@ -0,0 +1,226 @@
+import { DataAdapter, DataAdapterRecord, DataAdapterConfig } from "./DataAdapter";
+import { ReadOnlyDataView } from "../../data/ReadOnlyDataView";
+import { sorter } from "../../data/comparer";
+import { isArray } from "../../util/isArray";
+import { ArrayElementView } from "../../data/ArrayElementView";
+import { Accessor, getAccessor } from "../../data/getAccessor";
+import { Culture } from "../Culture";
+import { isDefined, isObject } from "../../util";
+import { RenderingContext } from "../RenderingContext";
+import { Instance } from "../Instance";
+import { View } from "../../data/View";
+import { Prop, Sorter, CollatorOptions } from "../Prop";
+
+export interface RecordStoreCache {
+   recordStoreCache: WeakMap<any, View>;
+   cacheByKey: Record<string | number, View>;
+   recordsAccessor?: Accessor;
+}
+
+export interface ArrayAdapterConfig extends DataAdapterConfig {
+   recordsBinding?: Prop<any[]>;
+   recordsAccessor?: Accessor | string;
+   keyField?: string;
+   cacheByKeyField?: boolean;
+   sortOptions?: CollatorOptions;
+   preserveOrder?: boolean;
+}
+
+export interface ExtendedSorter extends Sorter {
+   comparer?: (a: any, b: any) => number;
+   sortOptions?: CollatorOptions;
+}
+
+export interface ResolvedSorter {
+   getter: (x: any) => any;
+   factor: number;
+   compare: (a: any, b: any) => number;
+}
+
+export class ArrayAdapter<T = any> extends DataAdapter<T> {
+   declare public recordsAccessor: Accessor;
+   declare public recordsBinding?: Prop<T[]>;
+   declare public keyField: string | null;
+   declare public cacheByKeyField: boolean;
+   declare public sortOptions?: CollatorOptions;
+   declare public preserveOrder?: boolean;
+   declare isTreeAdapter: boolean;
+
+   declare protected sorter?: (data: DataAdapterRecord<T>[]) => DataAdapterRecord<T>[];
+
+   constructor(config?: ArrayAdapterConfig) {
+      super(config);
+   }
+
+   public init(): void {
+      this.recordsAccessor = getAccessor(this.recordsBinding ?? this.recordsAccessor);
+      this.recordName = this.recordName?.toString() || "$record";
+      this.indexName = this.indexName?.toString() || "$index";
+   }
+
+   public initInstance(context: RenderingContext, instance: Instance & Partial<RecordStoreCache>): void {
+      if (!instance.recordStoreCache) {
+         instance.recordStoreCache = new WeakMap();
+         instance.cacheByKey = {};
+      }
+
+      if (!instance.recordsAccessor && this.recordsAccessor) {
+         instance.recordsAccessor = this.recordsAccessor.bindInstance
+            ? this.recordsAccessor.bindInstance(instance)
+            : this.recordsAccessor;
+      }
+   }
+
+   public getRecords(
+      context: RenderingContext,
+      instance: Instance & Partial<RecordStoreCache>,
+      records: T[],
+      parentStore: View,
+   ): DataAdapterRecord<T>[] {
+      if (!instance.recordStoreCache) {
+         this.initInstance(context, instance);
+      }
+
+      return this.mapRecords(context, instance, records, parentStore, instance.recordsAccessor);
+   }
+
+   public mapRecords(
+      context: RenderingContext,
+      instance: Instance & Partial<RecordStoreCache>,
+      records: T[],
+      parentStore: View,
+      recordsAccessor?: Accessor,
+   ): DataAdapterRecord<T>[] {
+      let result: DataAdapterRecord<T>[] = [];
+
+      if (!instance.recordStoreCache) {
+         this.initInstance(context, instance);
+      }
+
+      if (isArray(records)) {
+         records.forEach((data, index) => {
+            if (this.filterFn && !this.filterFn(data)) return;
+
+            const record = this.mapRecord(context, instance, data, parentStore, recordsAccessor, index);
+            result.push(record);
+         });
+      }
+
+      if (this.sorter && !this.preserveOrder) {
+         result = this.sorter(result);
+      }
+
+      return result;
+   }
+
+   public mapRecord(
+      context: RenderingContext,
+      instance: Instance & Partial<RecordStoreCache>,
+      data: T,
+      parentStore: View,
+      recordsAccessor: Accessor | undefined,
+      index: number,
+   ): DataAdapterRecord<T> {
+      const key = this.cacheByKeyField && this.keyField && isObject(data) ? (data as any)[this.keyField] : null;
+      let recordStore = key != null ? instance.cacheByKey![key] : instance.recordStoreCache!.get(data);
+
+      if (recordsAccessor) {
+         if (!recordStore) {
+            recordStore = new ArrayElementView({
+               store: parentStore,
+               arrayAccessor: recordsAccessor,
+               itemIndex: index,
+               recordAlias: this.recordName,
+               indexAlias: this.indexName,
+               immutable: this.immutable,
+               sealed: this.sealed,
+            });
+         } else {
+            (recordStore as ArrayElementView).setStore(parentStore);
+            (recordStore as ArrayElementView).setIndex(index);
+         }
+      } else {
+         if (!recordStore) {
+            recordStore = new ReadOnlyDataView({
+               store: parentStore,
+               data: {
+                  [this.recordName]: data,
+                  [this.indexName]: index,
+               },
+               immutable: this.immutable,
+               sealed: this.sealed,
+            });
+         } else {
+            (recordStore as ReadOnlyDataView).setStore(parentStore);
+            (recordStore as ReadOnlyDataView).setData(data);
+         }
+      }
+
+      if (key != null) {
+         instance.cacheByKey![key] = recordStore;
+      } else if (isObject(data)) {
+         instance.recordStoreCache!.set(data, recordStore);
+      }
+
+      return {
+         store: recordStore,
+         index: index,
+         data: data,
+         type: "data",
+         key: this.keyField && isObject(data) ? (data as any)[this.keyField] : index,
+      };
+   }
+
+   public setFilter(filterFn?: (data: T) => boolean): void {
+      this.filterFn = filterFn;
+   }
+
+   public getComparer(sortOptions?: CollatorOptions): ((a: any, b: any) => number) | undefined {
+      return sortOptions ? Culture.getComparer(sortOptions) : undefined;
+   }
+
+   public buildSorter(sorters: ExtendedSorter[]): void {
+      if (isArray(sorters) && sorters.length > 0) {
+         let dataAccessor: (x: DataAdapterRecord<T>) => any;
+         let fieldValueMapper: (x: ExtendedSorter) => Prop<any>;
+
+         if (sorters.every((x) => x.field && x.value == null)) {
+            dataAccessor = (x) => x.data;
+            fieldValueMapper = (x) => ({ bind: x.field! });
+         } else {
+            dataAccessor = (x) => x.store.getData();
+            fieldValueMapper = (x) => ({ bind: this.recordName + "." + x.field });
+         }
+
+         this.sorter = sorter(
+            sorters.map((x) => {
+               const s: ExtendedSorter = Object.assign({}, x);
+               if (s.field && s.value == null) {
+                  s.value = fieldValueMapper(s);
+               }
+               if (!s.comparer) {
+                  s.comparer = this.getComparer(isDefined(s.sortOptions) ? s.sortOptions : this.sortOptions);
+               }
+               return s;
+            }),
+            dataAccessor,
+         );
+      } else {
+         this.sorter = undefined;
+      }
+   }
+
+   public sort(sorters?: Sorter[] | ExtendedSorter[]): void {
+      if (sorters) {
+         this.buildSorter(sorters as ExtendedSorter[]);
+      }
+   }
+}
+
+ArrayAdapter.prototype.immutable = false;
+ArrayAdapter.prototype.sealed = false;
+ArrayAdapter.prototype.keyField = null;
+ArrayAdapter.prototype.cacheByKeyField = true;
+ArrayAdapter.prototype.isTreeAdapter = false;
+
+ArrayAdapter.autoInit = true;