cx 25.10.1 → 26.0.1

package/src/widgets/Button.tsx

@@ -0,0 +1,201 @@
+/** @jsxImportSource react */
+import { Widget, VDOM, getContentArray } from "../ui/Widget";
+import { HtmlElement, HtmlElementConfig, HtmlElementInstance } from "./HtmlElement";
+import { yesNo } from "./overlay/alerts";
+import { Icon } from "./Icon";
+import { preventFocus } from "../ui/FocusManager";
+import { isFunction } from "../util/isFunction";
+import { isDefined } from "../util/isDefined";
+import { coalesce } from "../util/coalesce";
+import type { RenderingContext } from "../ui/RenderingContext";
+import type { Instance, WidgetData, RenderProps } from "../ui/Instance";
+import { YesNoResult } from "../ui/Instance";
+import { BooleanProp, StringProp, Prop, ModProp } from "../ui/Prop";
+import type { FormRenderingContext } from "./form/ValidationGroup";
+
+interface ButtonData extends WidgetData {
+   pressed?: boolean;
+   icon?: string | boolean;
+   disabled?: boolean;
+   enabled?: boolean;
+}
+
+export interface ButtonConfig extends HtmlElementConfig {
+   /** Confirmation text or configuration object. See MsgBox.yesNo for more details. */
+   confirm?: Prop<string | Record<string, unknown>>;
+
+   /** If true button appears in pressed state. Useful for implementing toggle buttons. */
+   pressed?: BooleanProp;
+
+   /** Name of the icon to be put on the left side of the button. */
+   icon?: StringProp;
+
+   /** HTML tag to be used. Default is `button`. */
+   tag?: string;
+
+   /** Base CSS class to be applied to the element. Default is 'button'. */
+   baseClass?: string;
+
+   /**
+    * Determines if button should receive focus on mousedown event.
+    * Default is `false`, which means that focus can be set only using the keyboard `Tab` key.
+    */
+   focusOnMouseDown?: boolean;
+
+   /** Add type="submit" to the button. */
+   submit?: boolean;
+
+   /** Set to `true` to disable the button. */
+   disabled?: BooleanProp;
+
+   /** Set to `false` to disable the button. */
+   enabled?: BooleanProp;
+
+   /**
+    * Click handler.
+    *
+    * @param e - Event.
+    * @param instance - Cx widget instance that fired the event.
+    */
+   onClick?: string | ((e: MouseEvent, instance: Instance) => void);
+
+   onMouseDown?: string | ((e: MouseEvent, instance: Instance) => void);
+
+   /** Button type. */
+   type?: "submit" | "button";
+
+   /** If set to `true`, the Button will cause its parent Overlay (if one exists) to close. This, however, can be prevented if `onClick` explicitly returns `false`. */
+   dismiss?: boolean;
+
+   /** The form attribute specifies the form the button belongs to.
+    * The value of this attribute must be equal to the `id` attribute of a `<form>` element in the same document.
+    */
+   form?: StringProp;
+}
+
+export class Button extends HtmlElement<ButtonConfig, HtmlElementInstance> {
+   constructor(config?: ButtonConfig) {
+      super(config);
+   }
+
+   declare icon?: boolean | string;
+   declare focusOnMouseDown?: boolean;
+   declare submit?: boolean;
+   declare dismiss?: boolean;
+   declare onMouseDown?: string | ((e: MouseEvent, instance: Instance) => void);
+   declare baseClass: string;
+
+   declareData(...args: Record<string, unknown>[]): void {
+      super.declareData(...args, {
+         confirm: { structured: true },
+         pressed: undefined,
+         icon: undefined,
+         disabled: undefined,
+         enabled: undefined,
+      });
+   }
+
+   prepareData(context: RenderingContext, instance: HtmlElementInstance): void {
+      const { data } = instance;
+      data.stateMods = {
+         ...data.stateMods,
+         pressed: data.pressed,
+      };
+      if (isDefined(data.enabled)) data.disabled = !data.enabled;
+
+      super.prepareData(context, instance);
+   }
+
+   explore(context: FormRenderingContext, instance: HtmlElementInstance): void {
+      instance.data.parentDisabled = context.parentDisabled;
+      instance.data.parentStrict = context.parentStrict;
+
+      if (instance.cache("parentDisabled", context.parentDisabled)) instance.markShouldUpdate(context);
+      if (instance.cache("parentStrict", context.parentStrict)) instance.markShouldUpdate(context);
+
+      super.explore(context, instance);
+   }
+
+   attachProps(context: RenderingContext, instance: HtmlElementInstance, props: RenderProps): void {
+      super.attachProps(context, instance, props);
+
+      if (!this.focusOnMouseDown) {
+         props.onMouseDown = (e: React.MouseEvent) => {
+            if (this.onMouseDown && instance.invoke("onMouseDown", e.nativeEvent, instance) === false) return;
+            preventFocus(e);
+         };
+      }
+
+      if (this.dismiss) {
+         const { onClick } = props;
+
+         props.onClick = (e: React.MouseEvent) => {
+            if (onClick) {
+               const result = onClick(e);
+               if (result === false) return;
+            }
+
+            if (instance.parentOptions && isFunction(instance.parentOptions.dismiss)) {
+               instance.parentOptions.dismiss();
+            }
+         };
+      }
+
+      if (this.tag === "button") props.type = this.submit ? "submit" : "button";
+
+      delete props.confirm;
+      delete props.dismiss;
+      delete props.pressed;
+      delete props.submit;
+      delete props.focusOnMouseDown;
+      delete props.icon;
+      delete props.enabled;
+
+      const { data } = instance;
+
+      props.disabled = coalesce(data.parentStrict ? data.parentDisabled : null, data.disabled, data.parentDisabled) as
+         | boolean
+         | undefined;
+
+      if (data.confirm) {
+         const oldOnClick = props.onClick;
+         props.onClick = (e: React.MouseEvent) => {
+            yesNo(data.confirm!).then((btn: string) => {
+               if (btn === YesNoResult.Yes && oldOnClick) {
+                  oldOnClick(e);
+               }
+            });
+         };
+      }
+
+      if (data.icon) {
+         const icon = Icon.render(data.icon, {
+            key: "icon",
+            className: this.CSS.element(this.baseClass, "icon"),
+         });
+         const children = getContentArray(props.children);
+         props.children = [icon, ...children];
+         props.className = this.CSS.expand(
+            props.className,
+            this.CSS.state("icon"),
+            children.length === 0 && this.CSS.state("empty"),
+         );
+
+         if (children.length === 0) {
+            (props.children as React.ReactNode[]).push(
+               <span key="baseline" className={this.CSS.element(this.baseClass, "baseline")}>
+                  &nbsp;
+               </span>,
+            );
+         }
+      }
+   }
+}
+
+Button.prototype.tag = "button";
+Button.prototype.baseClass = "button";
+Button.prototype.icon = false;
+Button.prototype.focusOnMouseDown = false;
+Button.prototype.submit = false;
+
+Widget.alias("button", Button);

package/src/widgets/Button.variables.scss

@@ -1,3 +1,6 @@
+@use "sass:color";
+@use "sass:map";
+
 $cx-default-button-font-family: $cx-default-box-font-family !default;
 $cx-default-button-font-size: $cx-default-box-font-size !default;
 $cx-default-button-font-weight: normal !default;
@@ -61,9 +64,9 @@ $cx-button-mods: (
          color: white,
       ),
       disabled: (
-         background-color: transparentize(#1f99f8, 0.5),
-         border-color: transparentize(#1e88e5, 0.9),
-         color: transparentize(white, 0.4),
+         background-color: color.adjust(#1f99f8, $alpha: -0.5),
+         border-color: color.adjust(#1e88e5, $alpha: -0.9),
+         color: color.adjust(white, $alpha: -0.4),
       ),
       hover: (
          background-color: #1f99f8,
@@ -76,9 +79,9 @@ $cx-button-mods: (
          color: white,
       ),
       disabled: (
-         background-color: transparentize(#d32f2f, 0.4),
-         border-color: transparentize(#c62828, 0.9),
-         color: transparentize(white, 0.5),
+         background-color: color.adjust(#d32f2f, $alpha: -0.4),
+         border-color: color.adjust(#c62828, $alpha: -0.9),
+         color: color.adjust(white, $alpha: -0.5),
       ),
       hover: (
          background-color: #d32f2f,
@@ -92,16 +95,16 @@ $cx-button-mods: (
          box-shadow: none,
       ),
       hover:
-         map-merge(
-            map-get($cx-list-item, hover),
+         map.merge(
+            map.get($cx-list-item, hover),
             (
                box-shadow: none,
                border-color: transparent,
             )
          ),
       focus:
-         map-merge(
-            map-get($cx-list-item, selected-cursor),
+         map.merge(
+            map.get($cx-list-item, selected-cursor),
             (
                box-shadow: none,
                border-color: transparent,

package/src/widgets/CxCredit.scss

@@ -1,8 +1,10 @@
+@use "sass:map";
+
 @mixin cx-cxcredit($name: "cxcredit", $besm: $cx-besm) {
-   $block: map-get($besm, block);
-   $element: map-get($besm, element);
-   $state: map-get($besm, state);
-   $mod: map-get($besm, mod);
+   $block: map.get($besm, block);
+   $element: map.get($besm, element);
+   $state: map.get($besm, state);
+   $mod: map.get($besm, mod);
 
    .#{$block}#{$name} {
       width: 50px;

package/src/widgets/CxCredit.tsx

@@ -0,0 +1,46 @@
+import { Widget, VDOM } from "../ui/Widget";
+import { HtmlElement, HtmlElementConfig, HtmlElementInstance } from "./HtmlElement";
+import { Icon } from "./Icon";
+import { RenderingContext } from "../ui/RenderingContext";
+import { RenderProps } from "../ui/Instance";
+
+export interface CxCreditConfig extends HtmlElementConfig {}
+
+export class CxCredit extends HtmlElement<CxCreditConfig, HtmlElementInstance> {
+   declare baseClass: string;
+
+   constructor(config?: CxCreditConfig) {
+      super(config);
+   }
+
+   init(): void {
+      this.tooltip = {
+         mouseTrap: true,
+         title: "Credits",
+         items: (
+            <cx>
+               <div ws>
+                  User interface of this project is implemented using the CxJS framework. For more information about
+                  CxJS, please visit
+                  <a href="https://cxjs.io/" target="_blank">
+                     the CxJS homepage
+                  </a>
+                  .
+               </div>
+            </cx>
+         ),
+      };
+      super.init();
+   }
+
+   attachProps(context: RenderingContext, instance: HtmlElementInstance, props: RenderProps): void {
+      props.children = Icon.render("cx", {
+         className: this.CSS.element(this.baseClass, "icon"),
+      });
+   }
+}
+
+CxCredit.prototype.baseClass = "cxcredit";
+CxCredit.prototype.tag = "div";
+
+Widget.alias("cx-credit", CxCredit);

package/src/widgets/DocumentTitle.ts

@@ -0,0 +1,92 @@
+import { Widget, WidgetConfig } from "../ui/Widget";
+import { RenderingContext } from "../ui/RenderingContext";
+import { Instance } from "../ui/Instance";
+import { StringProp } from "../ui/Prop";
+
+export interface DocumentTitleConfig extends WidgetConfig {
+   /** Text value to be used for the document title. */
+   value?: StringProp;
+
+   /** Deprecated. Use `action: "append"` instead. */
+   append?: boolean;
+
+   /** How to combine the title with existing document title. Default is `append`. */
+   action?: "append" | "replace" | "prepend";
+
+   /** Separator used when appending or prepending to the title. Default is empty string. */
+   separator?: StringProp;
+}
+
+export class DocumentTitle extends Widget<DocumentTitleConfig> {
+   declare value?: StringProp;
+   declare text?: StringProp;
+   declare append?: boolean;
+   declare action?: "append" | "replace" | "prepend";
+   declare separator?: StringProp;
+
+   constructor(config?: DocumentTitleConfig) {
+      super(config);
+   }
+
+   init(): void {
+      if (this.value) this.text = this.value;
+
+      if (this.append) this.action = "append";
+
+      super.init();
+   }
+
+   declareData(...args: Record<string, unknown>[]): void {
+      super.declareData(...args, {
+         value: undefined,
+         text: undefined,
+         action: undefined,
+         separator: undefined,
+      });
+   }
+
+   explore(context: RenderingContext, instance: Instance): void {
+      if (!(context as any).documentTitle) {
+         (context as any).documentTitle = {
+            activeInstance: instance,
+            title: "",
+         };
+      }
+
+      let { data } = instance;
+
+      if (data.text) {
+         switch (data.action) {
+            case "append":
+               if ((context as any).documentTitle.title) (context as any).documentTitle.title += data.separator;
+               (context as any).documentTitle.title += data.text;
+               break;
+
+            case "prepend":
+               (context as any).documentTitle.title = data.text + data.separator + (context as any).documentTitle.title;
+               break;
+
+            default:
+            case "replace":
+               (context as any).documentTitle.title = data.text;
+               break;
+         }
+      }
+
+      super.explore(context, instance);
+   }
+
+   prepare(context: RenderingContext, instance: Instance): void {
+      if ((context as any).documentTitle.activeInstance == instance)
+         document.title = (context as any).documentTitle.title;
+   }
+
+   render(): null {
+      return null;
+   }
+}
+
+DocumentTitle.prototype.action = "append";
+DocumentTitle.prototype.separator = "";
+
+Widget.alias("document-title", DocumentTitle);

package/src/widgets/FlexBox.scss

@@ -1,5 +1,7 @@
+@use "sass:map";
+
 @mixin cx-flexbox-spacing($divider, $besm: $cx-besm) {
-   $state: map-get($besm, state);
+   $state: map.get($besm, state);
    @each $pad, $size in $cx-pad-size {
       &.#{$state}#{$pad}-hspacing {
          margin-left: cx-divide(-$size, $divider);
@@ -24,10 +26,10 @@
 }
 
 @mixin cx-flexbox($name: "flexbox", $besm: $cx-besm) {
-   $block: map-get($besm, block);
-   $element: map-get($besm, element);
-   $state: map-get($besm, state);
-   $mod: map-get($besm, mod);
+   $block: map.get($besm, block);
+   $element: map.get($besm, element);
+   $state: map.get($besm, state);
+   $mod: map.get($besm, mod);
 
    .#{$block}#{$name} {
       box-sizing: border-box;

package/src/widgets/FlexBox.tsx

@@ -0,0 +1,169 @@
+/** @jsxImportSource react */
+import { VDOM } from "../ui/Widget";
+import { ContainerBase, StyledContainerConfig } from "../ui/Container";
+import { isUndefined } from "../util/isUndefined";
+import { RenderingContext } from "../ui/RenderingContext";
+import { Instance } from "../ui/Instance";
+
+export interface FlexBoxConfig extends StyledContainerConfig {
+   /** Base CSS class. Default is `flexbox`. */
+   baseClass?: string;
+
+   /** Flex direction. Default is `row`.  */
+   direction?: string;
+
+   /**
+    * Add spacing between items by applying a margin to children.
+    * Allowed values are `xsmall`, `small`, `medium`, `large` and `xlarge`.
+    * Value `true` is equivalent to `medium`.
+    */
+   spacing?: string | boolean;
+
+   /**
+    * Add horizontal spacing between items by applying a margin to children.
+    * Allowed values are `xsmall`, `small`, `medium`, `large` and `xlarge`.
+    * Value `true` is equivalent to `medium`.
+    */
+   hspacing?: boolean | string;
+
+   /**
+    * Add vertical spacing between items by applying a margin to children.
+    * Allowed values are xsmall, small, medium, large and xlarge.
+    * Value true is equivalent to medium.
+    */
+   vspacing?: boolean | string;
+
+   /**
+    * Add padding to the box. Allowed values are `xsmall`, `small`, `medium`, `large` and `xlarge`.
+    *  Value `true` is equivalent to `medium`.
+    */
+   pad?: boolean | string;
+   padding?: boolean | string;
+
+   /**
+    * Add horizontal padding to the box. Allowed values are `xsmall`, `small`, `medium`, `large` and `xlarge`.
+    *  Value `true` is equivalent to `medium`.
+    */
+   hpad?: boolean | string;
+   hpadding?: boolean | string;
+
+   /**
+    * Add vertical padding to the box. Allowed values are `xsmall`, `small`, `medium`, `large` and `xlarge`.
+    *  Value `true` is equivalent to `medium`.
+    */
+   vpad?: boolean | string;
+   vpadding?: boolean | string;
+
+   wrap?: boolean;
+   align?: "start" | "center" | "end" | "baseline" | "stretch" | false;
+   justify?: "start" | "center" | "end" | "space-between" | "space-around" | "space-evenly" | false;
+   target?: string;
+
+   /**
+    * Set to true to add overflow styles required for deeply nested flexbox calculations.
+    */
+   nested?: boolean;
+}
+
+export class FlexBox extends ContainerBase<FlexBoxConfig, Instance> {
+   declare padding?: boolean | string;
+   declare hpadding?: boolean | string;
+   declare vpadding?: boolean | string;
+   declare spacing?: string | boolean;
+   declare hspacing?: boolean | string;
+   declare vspacing?: boolean | string;
+   declare pad?: boolean | string;
+   declare hpad?: boolean | string;
+   declare vpad?: boolean | string;
+   declare wrap?: boolean;
+   declare align?: "start" | "center" | "end" | "baseline" | "stretch" | false;
+   declare justify?: "start" | "center" | "end" | "space-between" | "space-around" | "space-evenly" | false;
+   declare target?: string;
+   declare nested?: boolean;
+   declare direction?: string;
+
+   constructor(config?: FlexBoxConfig) {
+      super(config);
+   }
+
+   init(): void {
+      if (this.padding) this.pad = this.padding;
+
+      if (this.hpadding) this.hpad = this.hpadding;
+
+      if (this.vpadding) this.vpad = this.vpadding;
+
+      this.hpad = isUndefined(this.hpad) ? this.pad : this.hpad;
+      this.vpad = isUndefined(this.vpad) ? this.pad : this.hpad;
+
+      if (this.hpad === true) this.hpad = "medium";
+
+      if (this.vpad === true) this.vpad = "medium";
+
+      this.hspacing = isUndefined(this.hspacing) ? this.spacing : this.hspacing;
+      this.vspacing = isUndefined(this.vspacing) ? this.spacing : this.vspacing;
+
+      if (this.hspacing === true) this.hspacing = "medium";
+
+      if (this.vspacing === true) this.vspacing = "medium";
+
+      super.init();
+   }
+
+   initInstance(context: RenderingContext, instance: Instance): void {
+      (instance as any).eventHandlers = instance.getJsxEventProps();
+      super.initInstance(context, instance);
+   }
+
+   prepareCSS(context: RenderingContext, instance: Instance): void {
+      let { data } = instance;
+      data.stateMods = {
+         ...data.stateMods,
+         [this.hpad + "-hpad"]: this.hpad,
+         [this.vpad + "-vpad"]: this.vpad,
+         nested: this.nested,
+      };
+      super.prepareCSS(context, instance);
+   }
+
+   render(context: RenderingContext, instance: Instance, key: string): React.ReactNode {
+      let { data } = instance;
+      let eventHandlers = (instance as any).eventHandlers;
+      let { CSS, baseClass } = this;
+      let flexboxMods = {
+         [this.hspacing + "-hspacing"]: this.hspacing,
+         [this.vspacing + "-vspacing"]: this.vspacing,
+         ["align-" + this.align]: this.align,
+         ["justify-" + this.justify]: this.justify,
+         wrap: this.wrap,
+         ["target-" + this.target]: true,
+         [this.direction!]: true,
+      };
+
+      return (
+         <div key={key} className={data.classNames as string} style={data.style as any} {...eventHandlers}>
+            <div className={CSS.element(baseClass!, "flexbox", flexboxMods)}>{this.renderChildren(context, instance)}</div>
+         </div>
+      );
+   }
+}
+
+FlexBox.prototype.baseClass = "flexbox";
+FlexBox.prototype.styled = true;
+FlexBox.prototype.direction = 'row';
+FlexBox.prototype.spacing = false;
+FlexBox.prototype.hspacing = undefined;
+FlexBox.prototype.vspacing = undefined;
+FlexBox.prototype.pad = false;
+FlexBox.prototype.hpad = undefined;
+FlexBox.prototype.vpad = undefined;
+FlexBox.prototype.wrap = false;
+FlexBox.prototype.align = false;
+FlexBox.prototype.justify = false;
+FlexBox.prototype.target = 'any';
+FlexBox.prototype.nested = false;
+
+export class FlexRow extends FlexBox {}
+
+export class FlexCol extends FlexBox {}
+FlexCol.prototype.direction = 'column';

package/src/widgets/Heading.scss

@@ -1,8 +1,10 @@
+@use "sass:map";
+
 @mixin cxb-heading($name: "heading", $besm: $cx-besm) {
-   $block: map-get($besm, block);
-   $element: map-get($besm, element);
-   $state: map-get($besm, state);
-   $mod: map-get($besm, mod);
+   $block: map.get($besm, block);
+   $element: map.get($besm, element);
+   $state: map.get($besm, state);
+   $mod: map.get($besm, mod);
 
    .#{$block}#{$name} {
       @include cx-add-rules($cx-caption-style-map);

package/src/widgets/Heading.ts

@@ -0,0 +1,43 @@
+import { HtmlElement, HtmlElementConfig, HtmlElementInstance } from "./HtmlElement";
+import { RenderingContext } from "../ui/RenderingContext";
+
+export interface HeadingConfig extends HtmlElementConfig {
+   /** Name of the HTML element to be rendered. Default is `div`. */
+   tag?: string;
+
+   /** Heading level. Allowed values go from 1 to 6. Default is 3. */
+   level?: number | string;
+
+   /** Base CSS class. Default is `heading`. */
+   baseClass?: string;
+}
+
+export class Heading extends HtmlElement<HeadingConfig, HtmlElementInstance> {
+   declare level?: number | string;
+
+   init(): void {
+      this.tag = `h${this.level}`;
+      super.init();
+   }
+
+   prepareData(context: RenderingContext, instance: HtmlElementInstance): void {
+      let { data } = instance;
+      data.stateMods = {
+         ...data.stateMods,
+         [`level-${this.level}`]: true,
+      };
+      super.prepareData(context, instance);
+   }
+
+   isValidHtmlAttribute(attrName: string): string | false {
+      switch (attrName) {
+         case "level":
+            return false;
+
+         default: return super.isValidHtmlAttribute(attrName);
+      }
+   }
+}
+
+Heading.prototype.level = 3;
+Heading.prototype.baseClass = "heading";

package/src/widgets/HighlightedSearchText.scss

@@ -1,12 +1,14 @@
+@use "sass:map";
+
 @mixin cxb-highlightedsearchtext(
    $name: "highlightedsearchtext",
    $styles: $cx-highlightedsearchtext-style-map,
    $besm: $cx-besm
 ) {
-   $block: map-get($besm, block);
-   $element: map-get($besm, element);
-   $state: map-get($besm, state);
-   $mod: map-get($besm, mod);
+   $block: map.get($besm, block);
+   $element: map.get($besm, element);
+   $state: map.get($besm, state);
+   $mod: map.get($besm, mod);
 
    .#{$block}#{$name} {
       @include cx-add-rules($styles);