@decaf-ts/ui-decorators 0.17.1 → 0.17.4

package/lib/types/graph/constants.d.cts

@@ -31,6 +31,11 @@ export type GraphNodeMetadata = {
     width?: number;
     connectionRules?: GraphConnectionRule;
     metadata?: Record<string, unknown>;
+    /**
+     * Per-group rendering choice for Schema-typed `@input` / `@output` properties
+     * (the one-vs-all toggle). See {@link GraphPortGroupMetadata}.
+     */
+    portGroups?: GraphPortGroupMetadata[];
 };
 export type GraphWorkflowNodeMetadata = {
     id: string;
@@ -61,6 +66,41 @@ export type GraphPortMetadata = {
     handle?: string;
     expand?: boolean;
     metadata?: Record<string, unknown>;
+    /**
+     * Marks this port as a "Schema port" declared via `@input` / `@output`.
+     *
+     * When `true` AND the property type is a Decaf `Model` (a "Schema"), the
+     * reader flattens the Schema's own `@input` / `@output` properties into the
+     * parent node's port list (unprefixed — no `<schemaProp>.` prefix), instead
+     * of producing a composite port with prefixed children. A `@input` Schema
+     * contributes only the Schema's `@input` properties; a `@output` Schema
+     * contributes only the Schema's `@output` properties. The carrier property
+     * itself (e.g. `inputSchema`) is not emitted as a port — it is the group
+     * carrier.
+     *
+     * Set automatically by `@input` / `@output`; NOT set by `@port`, so
+     * `@port`-decorated Schema-typed properties keep the legacy composite
+     * expansion (prefixed children).
+     */
+    schema?: boolean;
+};
+/**
+ * Metadata for a Schema port group — the one-vs-all rendering choice for a
+ * `@input` / `@output` Schema-typed property.
+ *
+ * `toggle: "all"` (default) renders each Schema property as its own connectable
+ * port on the canvas. `toggle: "single"` renders one grouped port that receives
+ * the whole object and maps it to the right place. The per-instance
+ * manual-fill (hide a port because its value is supplied via the CRUD field)
+ * is NOT carried here — that is the editor's port-toggle state in `node.data`.
+ */
+export type GraphPortGroupMetadata = {
+    /** The Schema-typed `@input` / `@output` property name that owns this group. */
+    property: string;
+    /** Render choice for this group. Defaults to `"all"`. */
+    toggle?: "single" | "all";
+    /** Optional label for the grouped port when `toggle === "single"`. */
+    label?: string;
 };
 export type GraphPortDefinition = {
     property: string;
@@ -98,6 +138,13 @@ export type GraphNodeDefinition = {
     ui?: Record<string, any>;
     graph?: GraphNodeMetadata;
     ports: GraphPortDefinition[];
+    /**
+     * Per-group rendering choice for Schema-typed `@input` / `@output` properties
+     * (the one-vs-all toggle). Derived from {@link GraphNodeMetadata.portGroups};
+     * every Schema-typed `@input` / `@output` property not listed defaults to
+     * `toggle: "all"`.
+     */
+    portGroups?: GraphPortGroupMetadata[];
 };
 export type GraphWorkflowDefinition = GraphNodeDefinition & {
     inputs: GraphPortDefinition[];

package/lib/types/graph/constants.d.mts

@@ -31,6 +31,11 @@ export type GraphNodeMetadata = {
     width?: number;
     connectionRules?: GraphConnectionRule;
     metadata?: Record<string, unknown>;
+    /**
+     * Per-group rendering choice for Schema-typed `@input` / `@output` properties
+     * (the one-vs-all toggle). See {@link GraphPortGroupMetadata}.
+     */
+    portGroups?: GraphPortGroupMetadata[];
 };
 export type GraphWorkflowNodeMetadata = {
     id: string;
@@ -61,6 +66,41 @@ export type GraphPortMetadata = {
     handle?: string;
     expand?: boolean;
     metadata?: Record<string, unknown>;
+    /**
+     * Marks this port as a "Schema port" declared via `@input` / `@output`.
+     *
+     * When `true` AND the property type is a Decaf `Model` (a "Schema"), the
+     * reader flattens the Schema's own `@input` / `@output` properties into the
+     * parent node's port list (unprefixed — no `<schemaProp>.` prefix), instead
+     * of producing a composite port with prefixed children. A `@input` Schema
+     * contributes only the Schema's `@input` properties; a `@output` Schema
+     * contributes only the Schema's `@output` properties. The carrier property
+     * itself (e.g. `inputSchema`) is not emitted as a port — it is the group
+     * carrier.
+     *
+     * Set automatically by `@input` / `@output`; NOT set by `@port`, so
+     * `@port`-decorated Schema-typed properties keep the legacy composite
+     * expansion (prefixed children).
+     */
+    schema?: boolean;
+};
+/**
+ * Metadata for a Schema port group — the one-vs-all rendering choice for a
+ * `@input` / `@output` Schema-typed property.
+ *
+ * `toggle: "all"` (default) renders each Schema property as its own connectable
+ * port on the canvas. `toggle: "single"` renders one grouped port that receives
+ * the whole object and maps it to the right place. The per-instance
+ * manual-fill (hide a port because its value is supplied via the CRUD field)
+ * is NOT carried here — that is the editor's port-toggle state in `node.data`.
+ */
+export type GraphPortGroupMetadata = {
+    /** The Schema-typed `@input` / `@output` property name that owns this group. */
+    property: string;
+    /** Render choice for this group. Defaults to `"all"`. */
+    toggle?: "single" | "all";
+    /** Optional label for the grouped port when `toggle === "single"`. */
+    label?: string;
 };
 export type GraphPortDefinition = {
     property: string;
@@ -98,6 +138,13 @@ export type GraphNodeDefinition = {
     ui?: Record<string, any>;
     graph?: GraphNodeMetadata;
     ports: GraphPortDefinition[];
+    /**
+     * Per-group rendering choice for Schema-typed `@input` / `@output` properties
+     * (the one-vs-all toggle). Derived from {@link GraphNodeMetadata.portGroups};
+     * every Schema-typed `@input` / `@output` property not listed defaults to
+     * `toggle: "all"`.
+     */
+    portGroups?: GraphPortGroupMetadata[];
 };
 export type GraphWorkflowDefinition = GraphNodeDefinition & {
     inputs: GraphPortDefinition[];

package/lib/types/index.d.cts

@@ -15,19 +15,19 @@ export * from "./ui/index.d.cts";
  * @const VERSION
  * @memberOf module:ui-decorators
  */
-export declare const VERSION = "0.17.0";
+export declare const VERSION = "0.17.3";
 /**
  * @description Represents the current commit hash of the module build.
  * @summary Stores the current git commit hash for the package. The build replaces
  * the placeholder with the actual commit hash at publish time.
  * @const COMMIT
  */
-export declare const COMMIT = "1c6464a";
+export declare const COMMIT = "ff23f4a";
 /**
  * @description Represents the full version string of the module.
  * @summary Stores the semver version and commit hash for the package.
  * The build replaces the placeholder with the actual `<version>-<commit>` value at publish time.
  * @const FULL_VERSION
  */
-export declare const FULL_VERSION = "0.17.0-1c6464a";
+export declare const FULL_VERSION = "0.17.3-ff23f4a";
 export declare const PACKAGE_NAME = "@decaf-ts/ui-decorators";

package/lib/types/index.d.mts

@@ -15,19 +15,19 @@ export * from "./ui/index.d.mts";
  * @const VERSION
  * @memberOf module:ui-decorators
  */
-export declare const VERSION = "0.17.0";
+export declare const VERSION = "0.17.3";
 /**
  * @description Represents the current commit hash of the module build.
  * @summary Stores the current git commit hash for the package. The build replaces
  * the placeholder with the actual commit hash at publish time.
  * @const COMMIT
  */
-export declare const COMMIT = "1c6464a";
+export declare const COMMIT = "ff23f4a";
 /**
  * @description Represents the full version string of the module.
  * @summary Stores the semver version and commit hash for the package.
  * The build replaces the placeholder with the actual `<version>-<commit>` value at publish time.
  * @const FULL_VERSION
  */
-export declare const FULL_VERSION = "0.17.0-1c6464a";
+export declare const FULL_VERSION = "0.17.3-ff23f4a";
 export declare const PACKAGE_NAME = "@decaf-ts/ui-decorators";

package/lib/types/model/decorators.d.cts

@@ -1,4 +1,4 @@
-import { IPagedComponentProperties } from "../ui/interfaces.d.cts";
+import { IPagedComponentProperties } from "../ui/types.d.cts";
 /**
  * @description Decorator that tags a class as a UI model
  * @summary Adds rendering capabilities to a model class by providing a render method

package/lib/types/model/decorators.d.mts

@@ -1,4 +1,4 @@
-import { IPagedComponentProperties } from "../ui/interfaces.d.mts";
+import { IPagedComponentProperties } from "../ui/types.d.mts";
 /**
  * @description Decorator that tags a class as a UI model
  * @summary Adds rendering capabilities to a model class by providing a render method

package/lib/types/ui/Rendering.d.cts

@@ -1,5 +1,10 @@
-import { FieldDefinition } from "./types.d.cts";
+import { DecafSpinnerOptions, DecafToastOptions, FieldDefinition } from "./types.d.cts";
 import { Model, ValidationMetadata } from "@decaf-ts/decorator-validation";
+import { IDecafModal } from "./interfaces/IDecafModal.d.cts";
+import { DecafComponent } from "./DecafComponent.d.cts";
+import { IDecafSpinner } from "./interfaces/IDecafSpinner.d.cts";
+import { IDecafRouter } from "./interfaces/IDecafRouter.d.cts";
+import { IDecafToast } from "./interfaces/IDecafToast.d.cts";
 /**
  * @description Abstract class for rendering UI components based on model metadata.
  * @summary The RenderingEngine class provides a framework for converting model metadata into UI field definitions.
@@ -38,6 +43,10 @@ export declare abstract class RenderingEngine<T = void, R = FieldDefinition<T>>
      */
     protected initialized: boolean;
     protected constructor(flavour: string);
+    abstract getModal<C extends DecafComponent<Model>>(component: Partial<C>, ...args: any[]): Promise<IDecafModal>;
+    abstract getToast(options: DecafToastOptions): Promise<IDecafToast>;
+    abstract getSpinner(options: DecafSpinnerOptions): Promise<IDecafSpinner>;
+    abstract router(): IDecafRouter;
     /**
      * @description Initializes the rendering engine.
      * @summary Abstract method to be implemented by subclasses for specific initialization logic.

package/lib/types/ui/Rendering.d.mts

@@ -1,5 +1,10 @@
-import { FieldDefinition } from "./types.d.mts";
+import { DecafSpinnerOptions, DecafToastOptions, FieldDefinition } from "./types.d.mts";
 import { Model, ValidationMetadata } from "@decaf-ts/decorator-validation";
+import { IDecafModal } from "./interfaces/IDecafModal.d.mts";
+import { DecafComponent } from "./DecafComponent.d.mts";
+import { IDecafSpinner } from "./interfaces/IDecafSpinner.d.mts";
+import { IDecafRouter } from "./interfaces/IDecafRouter.d.mts";
+import { IDecafToast } from "./interfaces/IDecafToast.d.mts";
 /**
  * @description Abstract class for rendering UI components based on model metadata.
  * @summary The RenderingEngine class provides a framework for converting model metadata into UI field definitions.
@@ -38,6 +43,10 @@ export declare abstract class RenderingEngine<T = void, R = FieldDefinition<T>>
      */
     protected initialized: boolean;
     protected constructor(flavour: string);
+    abstract getModal<C extends DecafComponent<Model>>(component: Partial<C>, ...args: any[]): Promise<IDecafModal>;
+    abstract getToast(options: DecafToastOptions): Promise<IDecafToast>;
+    abstract getSpinner(options: DecafSpinnerOptions): Promise<IDecafSpinner>;
+    abstract router(): IDecafRouter;
     /**
      * @description Initializes the rendering engine.
      * @summary Abstract method to be implemented by subclasses for specific initialization logic.

package/lib/types/ui/decorators.d.cts

@@ -1,5 +1,5 @@
 import { UIKeys } from "./constants.d.cts";
-import { CrudOperationKeys, UIEventName, UIFunctionLike, UILayoutCol } from "./types.d.cts";
+import { CrudOperationKeys, UIEventHandler, UIEventName, UIFunctionLike, UILayoutCol } from "./types.d.cts";
 /**
  * @description Decorator that hides a property during specific CRUD operations
  * @summary Controls property visibility based on operation type
@@ -425,23 +425,24 @@ export declare function uipageprop(page?: number): (original: any, propertyKey?:
  * }
  * ```
  */
-export declare function uion(event: UIEventName | Record<string, UIFunctionLike>, handler: UIFunctionLike): (original: object, propertyKey?: string) => void;
+export declare function uion(event: UIEventName, handler: UIEventHandler): (original: object, propertyKey?: string) => void;
+export declare function uion(events: Record<string, UIEventHandler>): (original: object, propertyKey?: string) => void;
 /**
  * A decorator function that associates a UI click handler with the 'handleClick' event.
  *
- * @param handler - A function that conforms to the `UIFunctionLike` type, which will be executed
+ * @param handler - A function that conforms to the `UIEventHandler` type, which will be executed
  *                  when the 'handleClick' event is triggered.
  * @returns A decorated function that binds the handler to the 'handleClick' event.
  */
-export declare function uionclick(handler: UIFunctionLike): (original: object, propertyKey?: string) => void;
+export declare function uionclick(handler: UIEventHandler): (original: object, propertyKey?: string) => void;
 /**
  * A decorator function that associates a UI rendering handler with the 'render' event.
  *
- * @param handler - A function that conforms to the `UIFunctionLike` type, which will be executed
+ * @param handler - A function that conforms to the `UIEventHandler ` type, which will be executed
  *                  when the 'render' event is triggered.
  * @returns A decorated function that binds the handler to the 'render' event.
  */
-export declare function uionrender(handler: UIFunctionLike): (original: object, propertyKey?: string) => void;
+export declare function uionrender(handler: UIEventHandler): (original: object, propertyKey?: string) => void;
 /**
  * @description Decorator that marks a property as a column in a UI table
  * @summary Controls column ordering and optional value parsing for table props

package/lib/types/ui/decorators.d.mts

@@ -1,5 +1,5 @@
 import { UIKeys } from "./constants.d.mts";
-import { CrudOperationKeys, UIEventName, UIFunctionLike, UILayoutCol } from "./types.d.mts";
+import { CrudOperationKeys, UIEventHandler, UIEventName, UIFunctionLike, UILayoutCol } from "./types.d.mts";
 /**
  * @description Decorator that hides a property during specific CRUD operations
  * @summary Controls property visibility based on operation type
@@ -425,23 +425,24 @@ export declare function uipageprop(page?: number): (original: any, propertyKey?:
  * }
  * ```
  */
-export declare function uion(event: UIEventName | Record<string, UIFunctionLike>, handler: UIFunctionLike): (original: object, propertyKey?: string) => void;
+export declare function uion(event: UIEventName, handler: UIEventHandler): (original: object, propertyKey?: string) => void;
+export declare function uion(events: Record<string, UIEventHandler>): (original: object, propertyKey?: string) => void;
 /**
  * A decorator function that associates a UI click handler with the 'handleClick' event.
  *
- * @param handler - A function that conforms to the `UIFunctionLike` type, which will be executed
+ * @param handler - A function that conforms to the `UIEventHandler` type, which will be executed
  *                  when the 'handleClick' event is triggered.
  * @returns A decorated function that binds the handler to the 'handleClick' event.
  */
-export declare function uionclick(handler: UIFunctionLike): (original: object, propertyKey?: string) => void;
+export declare function uionclick(handler: UIEventHandler): (original: object, propertyKey?: string) => void;
 /**
  * A decorator function that associates a UI rendering handler with the 'render' event.
  *
- * @param handler - A function that conforms to the `UIFunctionLike` type, which will be executed
+ * @param handler - A function that conforms to the `UIEventHandler ` type, which will be executed
  *                  when the 'render' event is triggered.
  * @returns A decorated function that binds the handler to the 'render' event.
  */
-export declare function uionrender(handler: UIFunctionLike): (original: object, propertyKey?: string) => void;
+export declare function uionrender(handler: UIEventHandler): (original: object, propertyKey?: string) => void;
 /**
  * @description Decorator that marks a property as a column in a UI table
  * @summary Controls column ordering and optional value parsing for table props

package/lib/types/ui/index.d.cts

@@ -1,7 +1,6 @@
 export * from "./constants.d.cts";
 export * from "./decorators.d.cts";
 export * from "./errors.d.cts";
-export * from "./interfaces.d.cts";
 export * from "./Rendering.d.cts";
 export * from "./types.d.cts";
 export * from "./utils.d.cts";
@@ -9,3 +8,4 @@ export * from "./UIValidator.d.cts";
 export * from "./DecafComponent.d.cts";
 export * from "./DecafEventHandler.d.cts";
 export * from "./DecafTranslateService.d.cts";
+export * from "./interfaces/index.d.cts";

package/lib/types/ui/index.d.mts

@@ -1,7 +1,6 @@
 export * from "./constants.d.mts";
 export * from "./decorators.d.mts";
 export * from "./errors.d.mts";
-export * from "./interfaces.d.mts";
 export * from "./Rendering.d.mts";
 export * from "./types.d.mts";
 export * from "./utils.d.mts";
@@ -9,3 +8,4 @@ export * from "./UIValidator.d.mts";
 export * from "./DecafComponent.d.mts";
 export * from "./DecafEventHandler.d.mts";
 export * from "./DecafTranslateService.d.mts";
+export * from "./interfaces/index.d.mts";

package/lib/types/ui/interfaces/IDecafModal.d.cts

@@ -0,0 +1,186 @@
+/**
+ * @description Interface for modal presentation and lifecycle control in Decaf UI.
+ * @summary Describes the public contract for modal configuration, presentation,
+ * dismissal, and event handling used by the modal component layer.
+ *
+ * @module ui/interfaces/IDecafModal
+ * @memberOf module:ui-decorators
+ */
+import { Model } from "@decaf-ts/decorator-validation";
+import { DecafComponent } from "../DecafComponent.d.cts";
+export interface IDecafModal extends DecafComponent<Model> {
+    /**
+     * @description Reference to the modal instance controller.
+     * @summary Exposes the dismiss capability used to close the modal programmatically.
+     */
+    modal?: any;
+    /**
+     * @description Title displayed in the modal header.
+     * @summary Optional header text rendered above the modal content.
+     */
+    title?: string;
+    /**
+     * @description Controls whether the modal is open.
+     * @summary Signals the current presentation state of the modal.
+     */
+    isOpen: boolean;
+    /**
+     * @description Optional tag used to identify the modal instance.
+     * @summary Provides a stable identifier that can be used by rendering and lookup logic.
+     */
+    tag?: string;
+    /**
+     * @description Additional modal configuration options.
+     * @summary Stores custom configuration passed into modal creation and presentation.
+     */
+    options?: Record<string, unknown>;
+    /**
+     * @description Global configuration values available to the modal.
+     * @summary Holds shared runtime data that can be consumed by modal content and handlers.
+     */
+    globals?: Record<string, unknown>;
+    /**
+     * @description Inline content rendered inside the modal body.
+     * @summary Accepts HTML text or DOM content to be sanitized and displayed.
+     */
+    inlineContent?: string | any;
+    /**
+     * @description Position of the inline content within the modal.
+     * @summary Determines whether inline content appears before or after the main body.
+     */
+    inlineContentPosition: "top" | "bottom";
+    /**
+     * @description Enables fullscreen presentation for the modal.
+     * @summary Controls whether the modal occupies the entire viewport.
+     */
+    fullscreen: boolean;
+    /**
+     * @description Enables expandable presentation for the modal.
+     * @summary Signals whether the modal can be expanded by the user.
+     */
+    expandable: boolean;
+    /**
+     * @description Controls border rendering for the modal content.
+     * @summary Enables or disables visual borders according to the component styling rules.
+     */
+    borders: boolean;
+    /**
+     * @description Enables lightbox presentation for the modal.
+     * @summary Controls whether the modal is displayed with a lightbox-style overlay.
+     */
+    lightBox: boolean;
+    /**
+     * @description Controls the transparency of the modal header.
+     * @summary Indicates whether the modal header should be rendered with a transparent background.
+     */
+    headerTransparent: boolean;
+    /**
+     * @description Sets the background color of the modal header.
+     * @summary Stores the header color token used to style the modal header region.
+     */
+    headerBackground: string;
+    /**
+     * @description Controls the visibility of the modal header.
+     * @summary Indicates whether the header section should be rendered.
+     */
+    showHeader: boolean;
+    /**
+     * @description Controls the visibility of the modal close button.
+     * @summary Indicates whether the close action should be shown in the header.
+     */
+    showCloseButton: boolean;
+    /**
+     * @description Emits modal dismiss details.
+     * @summary Notifies consumers when the modal is about to be dismissed.
+     */
+    willDismissEvent: {
+        emit(value: unknown): void;
+    };
+    /**
+     * @description Indicates whether the modal content is expanded.
+     * @summary Tracks the current expanded or collapsed state of the modal body.
+     */
+    expanded: boolean;
+    /**
+     * @description Defines the icon color used by the modal.
+     * @summary Stores the color token used for modal icons and actions.
+     */
+    iconColor: string;
+    /**
+     * @description Initializes the modal component state.
+     * @summary Prepares the modal before presentation and applies inline content sanitization.
+     *
+     * @return {Promise<void>} Resolves when initialization completes.
+     */
+    ngOnInit(): Promise<void>;
+    /**
+     * @description Prepares the modal with the provided options.
+     * @summary Merges defaults, applies global runtime settings, and registers custom handlers.
+     *
+     * @param {Record<string, unknown>} [options={}] Additional modal initialization options.
+     * @return {Promise<void>} Resolves when preparation completes.
+     */
+    prepare(options?: Record<string, unknown>): Promise<void>;
+    /**
+     * @description Sanitizes and normalizes inline content.
+     * @summary Converts DOM content to HTML text when needed and prepares it for safe rendering.
+     *
+     * @return {void} Does not return a value.
+     */
+    parseInlineContent(): void;
+    /**
+     * @description Creates and presents the modal.
+     * @summary Prepares the modal, presents it, and returns the active modal instance contract.
+     *
+     * @param {Record<string, unknown>} [props={}] Modal properties used during creation.
+     * @return {Promise<any>} Resolves with the modal instance contract.
+     */
+    create(props?: Record<string, unknown>): Promise<any>;
+    /**
+     * @description Presents the modal.
+     * @summary Sets the modal as visible and triggers any presentation-time updates.
+     *
+     * @return {Promise<void>} Resolves when the modal is visible.
+     */
+    present(): Promise<void>;
+    /**
+     * @description Handles a custom event triggered by the modal.
+     * @summary Stops event propagation when needed and routes the event to confirm or cancel actions.
+     *
+     * @param {any} event Event payload emitted by the modal.
+     * @return {Promise<void>} Resolves when event handling completes.
+     */
+    handleEvent(event: any): Promise<void>;
+    /**
+     * @description Handles the modal dismiss event.
+     * @summary Emits the dismiss payload and returns the overlay detail object to callers.
+     *
+     * @param {any} event Dismiss event emitted by the modal.
+     * @return {Promise<{ data?: unknown }>} Resolves with the dismiss event details.
+     */
+    handleWillDismiss(event: any): Promise<{
+        data?: unknown;
+    }>;
+    /**
+     * @description Toggles the expanded state of the modal.
+     * @summary Switches between expanded and collapsed presentation modes.
+     *
+     * @return {void} Does not return a value.
+     */
+    handleExpandToggle(): void;
+    /**
+     * @description Cancels the modal.
+     * @summary Dismisses the modal using the cancel role.
+     *
+     * @return {Promise<void>} Resolves when the modal has been dismissed.
+     */
+    cancel(): Promise<void>;
+    /**
+     * @description Confirms the modal.
+     * @summary Dismisses the modal using the confirm role and optional event data.
+     *
+     * @param {any} [event] Optional event payload forwarded to the dismiss action.
+     * @return {Promise<void>} Resolves when the modal has been dismissed.
+     */
+    confirm(event?: any): Promise<void>;
+}