@decaf-ts/ui-decorators 0.17.11 → 0.19.0

package/lib/types/user-requests/index.d.mts

@@ -0,0 +1,15 @@
+/**
+ * @module ui-decorators/user-requests
+ * @summary Backend binding surface for the User Request Resolution Engine.
+ * @description Framework-agnostic core of the engine: no Angular or DOM
+ * imports, safe for pure-Node (backend) bundles. Handlers are registered via
+ * `@userRequest(reference)` (metadata) and resolved/dispatched through the
+ * static `UserRequestHandler` methods; example handlers and rendering-engine
+ * mocks live only in the test tree, never under `src`. Frontend bindings live
+ * in `for-angular`.
+ */
+export * from "./constants.d.mts";
+export * from "./errors.d.mts";
+export * from "./types.d.mts";
+export * from "./UserRequestHandler.d.mts";
+export * from "./decorators.d.mts";

package/lib/types/user-requests/types.d.cts

@@ -0,0 +1,36 @@
+/**
+ * @module ui-decorators/user-requests/types
+ * @summary Framework-agnostic contracts for the User Request Resolution Engine.
+ * @description No Angular or DOM imports are allowed here so the `user-requests`
+ * entry point stays consumable from pure-Node (backend) bundles.
+ */
+import type { RenderingEngine } from "../ui/Rendering.d.cts";
+/**
+ * @description A user request payload. `id` identifies the request instance,
+ * `type` is the keyed handler reference used for resolution — handlers are
+ * dispatched via `UserRequestHandler.handle(request, renderingEngine)`, which
+ * resolves the registered handler class by `request.type || request.id` — and
+ * `payload` carries optional request data.
+ * @template T The shape of the optional request data.
+ */
+export interface UserRequest<T = unknown> {
+    id: string;
+    type: string;
+    payload?: T;
+}
+/**
+ * @description The rendering-engine surface a user request handler needs.
+ * Exposes exactly the four real `RenderingEngine` methods a handler drives
+ * (modal, toast, spinner and router); no duplicated rendering types.
+ * @summary The four real `RenderingEngine` methods handed to handlers.
+ */
+export type RenderingFacade = Pick<RenderingEngine, "getModal" | "getToast" | "getSpinner" | "router">;
+/**
+ * @description Metadata recorded by `@userRequest(reference)` on a handler
+ * class and read back via `UserRequestHandler.getMetadata(target)`. `reference`
+ * is the request id/type the handler is registered for.
+ * @summary Metadata recorded on a `@userRequest`-decorated handler class.
+ */
+export interface UserRequestHandlerMetadata {
+    reference: string;
+}

package/lib/types/user-requests/types.d.mts

@@ -0,0 +1,36 @@
+/**
+ * @module ui-decorators/user-requests/types
+ * @summary Framework-agnostic contracts for the User Request Resolution Engine.
+ * @description No Angular or DOM imports are allowed here so the `user-requests`
+ * entry point stays consumable from pure-Node (backend) bundles.
+ */
+import type { RenderingEngine } from "../ui/Rendering.d.mts";
+/**
+ * @description A user request payload. `id` identifies the request instance,
+ * `type` is the keyed handler reference used for resolution — handlers are
+ * dispatched via `UserRequestHandler.handle(request, renderingEngine)`, which
+ * resolves the registered handler class by `request.type || request.id` — and
+ * `payload` carries optional request data.
+ * @template T The shape of the optional request data.
+ */
+export interface UserRequest<T = unknown> {
+    id: string;
+    type: string;
+    payload?: T;
+}
+/**
+ * @description The rendering-engine surface a user request handler needs.
+ * Exposes exactly the four real `RenderingEngine` methods a handler drives
+ * (modal, toast, spinner and router); no duplicated rendering types.
+ * @summary The four real `RenderingEngine` methods handed to handlers.
+ */
+export type RenderingFacade = Pick<RenderingEngine, "getModal" | "getToast" | "getSpinner" | "router">;
+/**
+ * @description Metadata recorded by `@userRequest(reference)` on a handler
+ * class and read back via `UserRequestHandler.getMetadata(target)`. `reference`
+ * is the request id/type the handler is registered for.
+ * @summary Metadata recorded on a `@userRequest`-decorated handler class.
+ */
+export interface UserRequestHandlerMetadata {
+    reference: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decaf-ts/ui-decorators",
-  "version": "0.17.11",
+  "version": "0.19.0",
   "description": "Extension of decorator validation to ui elements to allow for web integration",
   "type": "module",
   "exports": {
@@ -25,6 +25,17 @@
         "default": "./lib/cjs/graph/index.cjs"
       },
       "default": "./lib/esm/graph/index.js"
+    },
+    "./user-requests": {
+      "import": {
+        "types": "./lib/types/user-requests/index.d.mts",
+        "default": "./lib/esm/user-requests/index.js"
+      },
+      "require": {
+        "types": "./lib/types/user-requests/index.d.cts",
+        "default": "./lib/cjs/user-requests/index.cjs"
+      },
+      "default": "./lib/esm/user-requests/index.js"
     }
   },
   "types": "./lib/types/index.d.mts",
@@ -47,7 +58,7 @@
     "lint": "eslint .",
     "lint-fix": "eslint --fix .",
     "prepare-pr": "npm run lint-fix && npm run build:prod && npm run coverage && npm run docs",
-    "prepare-release": "npm run lint-fix && npm run build:prod && npm run coverage && npm run docs",
+    "prepare-release": "npm run lint-fix && npm run build:prod && npm run coverage",
     "release": "./bin/tag-release.sh",
     "clean-publish": "npx clean-publish",
     "drawings": "for FILE in workdocs/drawings/*.drawio; do echo \"converting $FILE to image...\" && docker run --rm -v $(pwd):/data rlespinasse/drawio-export --format png $FILE; done && cp -rf workdocs/drawings/export/* workdocs/resources/",
@@ -108,9 +119,12 @@
     "@types/jest": "^30.0.0"
   },
   "dependencies": {
+    "@decaf-ts/core": "latest",
     "@decaf-ts/db-decorators": "latest",
     "@decaf-ts/decoration": "latest",
-    "@decaf-ts/decorator-validation": "latest"
+    "@decaf-ts/decorator-validation": "latest",
+    "better-docs": "^2.7.3",
+    "taffydb": "^2.7.3"
   },
   "main": "./lib/cjs/index.cjs",
   "module": "./lib/esm/index.js",
@@ -123,5 +137,9 @@
     "./lib/cjs/graph/overrides/index.cjs",
     "./lib/cjs/graph/overrides/overrides.cjs",
     "./lib/cjs/model/overrides.cjs"
-  ]
+  ],
+  "overrides": {
+    "test-exclude": "^7.0.2",
+    "brace-expansion": "^5.0.8"
+  }
 }