jsf.js_next_gen 4.1.0-beta.2 → 4.1.0-beta.21

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "jsf.js_next_gen",
-  "version": "4.1.0-beta.2",
+  "version": "4.1.0-beta.21",
   "description": "A next generation typescript reimplementation of jsf.js",
   "main": "dist/window/faces.js",
   "scripts": {
     "doc": "npx typedoc --tsconfig src/main/typescript/tsconfig-typedoc.json",
-    "test": "cross-env  mocha",
+    "typecheck": "tsc --noEmit --project src/main/typescript/tsconfig.test.json",
+    "test": "npm run typecheck && cross-env mocha",
     "coverage": "cross-env nyc --reporter=html --reporter=text mocha",
-    "build-production": "NODE_OPTIONS='--import tsx' webpack --mode production --env FILE_NAME=jsf  && tsx ./remap.ts --production",
-    "build-development": "NODE_OPTIONS='--import tsx' webpack --mode development --env FILE_NAME=jsf-development  && tsx ./remap.ts --development",
-    "build": "npm run doc && npm run build-development && npm run build-production",
+    "build-bundles": "cross-env NODE_OPTIONS=\"--import tsx\" webpack",
+    "build-production": "cross-env NODE_OPTIONS=\"--import tsx\" webpack --mode production",
+    "build-development": "cross-env NODE_OPTIONS=\"--import tsx\" webpack --mode development",
+    "build-dts-compile": "tsc -p src/main/typescript/tsconfig.dts.json",
+    "build-dts": "npm run build-dts-compile && node scripts/build-dts.mjs",
+    "build": "npm run doc && npm run build-bundles && npm run build-dts",
     "serve": "npx http-server -p 8900 -b -g -o ./dist/"
   },
   "keywords": [
@@ -21,32 +25,32 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "^1.0.2",
+    "@microsoft/api-extractor": "^7.58.8",
     "@types/chai": "^5.2.3",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.9.3",
     "@types/sinon": "^21.0.1",
     "babel-plugin-syntax-dynamic-import": "^6.18.0",
     "chai": "^6.2.2",
     "cross-env": "^10.1.0",
+    "global-jsdom": "^29.0.0",
     "html-webpack-plugin": "^5.6.7",
     "http-server": "^14.1.1",
-    "jsdom": "^29.1.0",
-    "jsdom-global": "^3.0.2",
-    "mocha": "^11.7.5",
+    "jsdom": "^29.1.1",
+    "mocha": "^11.7.6",
     "nise": "^6.1.5",
-    "npm-check-updates": "^22.0.1",
+    "npm-check-updates": "^22.2.3",
     "nyc": "^18.0.0",
-    "replace-in-file": "^8.4.0",
     "rxjs": "^7.8.2",
-    "sinon": "^21.1.2",
-    "terser-webpack-plugin": "^5.5.0",
-    "ts-loader": "^9.5.7",
+    "sinon": "^22.0.0",
+    "terser-webpack-plugin": "^5.6.1",
+    "ts-loader": "^9.6.0",
     "tsconfig-paths": "^4.2.0",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "typedoc": "^0.28.19",
     "typescript": "^6.0.3",
-    "webpack": "^5.106.2",
-    "webpack-cli": "^7.0.2"
+    "webpack": "^5.107.2",
+    "webpack-cli": "^7.0.3"
   },
   "overrides": {
     "diff": "^9.0.0",
@@ -54,6 +58,6 @@
     "uuid": "^14.0.0"
   },
   "dependencies": {
-    "mona-dish": "0.30.0"
+    "mona-dish": "0.50.0-beta.8"
   }
 }

package/scripts/build-dts.mjs

@@ -0,0 +1,239 @@
+/*! Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Programmatic api-extractor runner.
+ * Suppresses the "bundled TypeScript is older than project" noise that appears
+ * when the project uses a newer TypeScript than api-extractor bundles.
+ *
+ * After running api-extractor for faces, post-processes faces.d.ts into a
+ * global declaration file, then derives jsf.d.ts from it via deterministic
+ * text transforms (JSF 2.3 shim differences).
+ *
+ * Usage (called by npm scripts):
+ *   node scripts/build-dts.mjs
+ */
+
+import { Extractor, ExtractorConfig } from "@microsoft/api-extractor";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { readFileSync, writeFileSync } from "fs";
+
+// Suppress the "bundled TypeScript / newer than bundled" noise from api-extractor.
+function makeSuppressingWriter(original) {
+  return function (chunk, ...args) {
+    const text = typeof chunk === "string" ? chunk : chunk.toString();
+    if (
+      text.includes("bundled TypeScript version") ||
+      text.includes("newer than the bundled compiler engine")
+    ) {
+      return true;
+    }
+    return original.call(this, chunk, ...args);
+  };
+}
+process.stdout.write = makeSuppressingWriter(process.stdout.write.bind(process.stdout));
+process.stderr.write = makeSuppressingWriter(process.stderr.write.bind(process.stderr));
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, "..");
+
+// Resolve the local TypeScript compiler installed in the project.
+const typescriptCompilerFolder = resolve(projectRoot, "node_modules", "typescript");
+
+// --- Step 1: run api-extractor for faces.d.ts ---
+
+const configPath = resolve(projectRoot, "api-extractor.faces.json");
+console.log(`\napi-extractor: processing api-extractor.faces.json`);
+
+const extractorConfig = ExtractorConfig.loadFileAndPrepare(configPath);
+
+const result = Extractor.invoke(extractorConfig, {
+  localBuild: true,
+  typescriptCompilerFolder,
+  showVerboseMessages: false,
+});
+
+if (!result.succeeded) {
+  console.error("  ✖  api-extractor.faces.json — FAILED");
+  process.exit(1);
+}
+console.log("  ✔  api-extractor.faces.json — completed successfully");
+
+// --- Step 2: post-process faces.d.ts into a global declaration file ---
+
+/**
+ * Walks forward from openIdx counting braces, returns the index of the
+ * matching closing brace, or -1 if not found.
+ */
+function findClosingBrace(content, openIdx) {
+  let depth = 0;
+  for (let i = openIdx; i < content.length; i++) {
+    if (content[i] === "{") depth++;
+    else if (content[i] === "}") {
+      if (--depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Converts the api-extractor module output into a global declaration file:
+ *
+ *  A. Strips "export" from top-level namespace declarations so that
+ *     "declare namespace faces { ... }" is a global ambient namespace,
+ *     matching the runtime shape where faces/jsf hang off window.
+ *
+ *  B. Removes "export { }" which makes the file a TypeScript module
+ *     (and therefore prevents global treatment).
+ *
+ *  C. Inlines the top-level "declare namespace oam { ... }" block as a
+ *     nested "namespace oam { ... }" inside myfaces, fixing the
+ *     self-referential "const oam: typeof oam" that api-extractor emits.
+ */
+function makeGlobalDeclaration(content) {
+  content = content.replace(/\r\n/g, "\n");
+
+  // A. Remove "export" from top-level namespace declarations.
+  content = content.replace(/^export (declare namespace )/gm, "$1");
+
+  // B. Remove the module-marker line.
+  content = content.replace(/\nexport \{ \}\s*$/, "\n");
+
+  // D. api-extractor drops "export" from const declarations inside namespaces
+  //    (it preserves it for functions/types/interfaces but not consts).
+  //    Add it back so namespace members like faces.specversion are accessible.
+  content = content.replace(/^([ \t]+)const /gm, "$1export const ");
+
+  // C. Inline the top-level oam namespace into myfaces.
+  const oamNeedle = "\ndeclare namespace oam {";
+  const nsIdx = content.indexOf(oamNeedle);
+  if (nsIdx !== -1) {
+    const openIdx = content.indexOf("{", nsIdx + 1);
+    const closeIdx = findClosingBrace(content, openIdx);
+    if (closeIdx !== -1) {
+      // Extract inner content, add 4 extra spaces of indentation, and make
+      // each const member explicitly exported so myfaces.oam.X is accessible.
+      const inner = content
+        .slice(openIdx + 1, closeIdx)
+        .split("\n")
+        .map((l) => {
+          if (!l.trim().length) return "";
+          const indented = "    " + l;
+          // Top-level oam members had no 'export' (redundant at global scope);
+          // nested inside myfaces they need it for myfaces.oam.X to be visible.
+          return indented.replace(/^([ \t]+)const /, "$1export const ");
+        })
+        .join("\n")
+        .trimEnd();
+
+      // Find the cut point: the blank line immediately before the top-level
+      // JSDoc that precedes "declare namespace oam {".
+      // Top-level JSDoc lines start at column 0 ("/**"), while JSDoc inside
+      // namespaces is indented ("    /**"), so lastIndexOf("\n/**") safely
+      // targets the oam JSDoc without matching inner comments.
+      const jsdocAnchor = content.lastIndexOf("\n/**", nsIdx);
+      const cutFrom = jsdocAnchor !== -1 ? jsdocAnchor : nsIdx;
+
+      // Remove the top-level oam block first (preserves index validity for
+      // the const-oam replacement that follows).
+      content = content.slice(0, cutFrom) + content.slice(closeIdx + 1);
+      content = content.trimEnd() + "\n";
+
+      // Replace 'const oam: typeof oam;' with the inlined nested namespace.
+      // 'export namespace' so that myfaces.oam is visible to TypeScript.
+      content = content.replace(
+        /^([ \t]*)const oam: typeof oam;/m,
+        `$1export namespace oam {\n${inner}\n$1}`
+      );
+    }
+  }
+
+  return content;
+}
+
+const APACHE_HEADER =
+  "/*! Licensed to the Apache Software Foundation (ASF) under one or more\n" +
+  " * contributor license agreements.  See the NOTICE file distributed with\n" +
+  " * this work for additional information regarding copyright ownership.\n" +
+  " * The ASF licenses this file to you under the Apache License, Version 2.0\n" +
+  ' * (the "License"); you may not use this file except in compliance with\n' +
+  " * the License.  You may obtain a copy of the License at\n" +
+  " *\n" +
+  " *      http://www.apache.org/licenses/LICENSE-2.0\n" +
+  " *\n" +
+  " * Unless required by applicable law or agreed to in writing, software\n" +
+  ' * distributed under the License is distributed on an "AS IS" BASIS,\n' +
+  " * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n" +
+  " * See the License for the specific language governing permissions and\n" +
+  " * limitations under the License.\n" +
+  " */\n\n";
+
+function postProcessFaces(facesPath) {
+  let content = readFileSync(facesPath, "utf-8");
+  content = makeGlobalDeclaration(content);
+  content = APACHE_HEADER + content;
+  writeFileSync(facesPath, content, "utf-8");
+}
+
+// --- Step 3: derive jsf.d.ts from the post-processed faces.d.ts ---
+
+function generateJsfFromFaces(facesPath, jsfPath) {
+  let content = readFileSync(facesPath, "utf-8");
+
+  // Normalize line endings (faces.d.ts is already normalized by postProcessFaces,
+  // but guard here in case this function is ever called standalone).
+  content = content.replace(/\r\n/g, "\n");
+
+  // 1. Rename the main "faces" namespace to "jsf".
+  //    After postProcessFaces the declaration has no leading "export".
+  content = content.replace(
+    /^declare namespace faces \{/m,
+    "declare namespace jsf {"
+  );
+
+  // 2. Fix cross-namespace references in myfaces: faces.ajax. → jsf.ajax.
+  content = content.replace(/\bfaces\.ajax\./g, "jsf.ajax.");
+
+  // 3. Remove the contextpath JSDoc comment block + var declaration.
+  content = content.replace(
+    /[ \t]+\/\*\*\n[ \t]+\* Context Path[^\n]*\n[ \t]+\*\/\n[ \t]+var contextpath: string;\n/,
+    ""
+  );
+
+  // 4. Remove onerror param from push.init (not from ajax options).
+  content = content.replace(
+    / onerror: OnErrorHandler \| string \| null,/,
+    ""
+  );
+
+  // 5. Remove the @param onerror JSDoc line — first occurrence only (push.init jsdoc).
+  content = content.replace(
+    /\n[ \t]*\* @param onerror The function to be invoked when an error occurs\./,
+    ""
+  );
+
+  writeFileSync(jsfPath, content, "utf-8");
+}
+
+const facesPath = resolve(projectRoot, "dist/window/faces.d.ts");
+const jsfPath = resolve(projectRoot, "dist/window/jsf.d.ts");
+
+postProcessFaces(facesPath);
+console.log("  ✔  faces.d.ts — post-processed as global declaration");
+
+generateJsfFromFaces(facesPath, jsfPath);
+console.log("  ✔  jsf.d.ts — derived from faces.d.ts");

package/src/main/typescript/@types/definitions/index.d.ts

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 
+import type { faces, myfaces } from '../../api/_api';
+
 /**
- * Basic internal types used
- *
- * This file is only there to allow global calls into window, faces and ajax
- * in a typesafe manner, hence eliminating <b>any</b> casts.
+ * Internal utility types used throughout the implementation.
+ * Public API types live in _api.ts; these are build-only helpers.
  */
 declare global {
 
@@ -28,138 +28,38 @@ declare global {
     type AssocArr<T> = { [key: string]: T };
     type EvalFuncs = Array<Function | string>;
 
-
     type Options = {
         render ?: string,
-        execute ?: string,          //space separated list of client ids
-        onevent ?: Function,        // event handler callback
-        onerror ?: Function,        // error handler callback
-        params ?: AssocArr<any>,    // passthrough params
-        delay ?: number,            // delay in milliseconds
-        resetValues ?: boolean,     // if set to true jakarta.faces.partial.resetValues is sent
-        /* @deprecated non-spec conform fallback behavior that anything can be passed and is used as passthrough */
+        execute ?: string,
+        onevent ?: Function,
+        onerror ?: Function,
+        params ?: AssocArr<any>,
+        delay ?: number,
+        resetValues ?: boolean,
         [key: string]: any
     }
 
     type Context = AssocArr<any>;
     type ElemDef = Element | string;
 
-    /**
-     *  * <ul>
-     *     <li> errorData.type : &quot;error&quot;</li>
-     *     <li> errorData.status : the error status message</li>
-     *     <li> errorData.serverErrorName : the server error name in case of a server error</li>
-     *     <li> errorData.serverErrorMessage : the server error message in case of a server error</li>
-     *     <li> errorData.source  : the issuing source element which triggered the request </li>
-     *     <li> eventData.responseCode: the response code (aka http request response code, 401 etc...) </li>
-     *     <li> eventData.responseText: the response text </li>
-     *     <li> eventData.responseXML: the response xml </li>
-     * </ul>
-     */
-    interface IErrorData {
-        type: any;
-        status: string;
-        serverErrorName: string;
-        serverErrorMessage: string;
-        source: any;
-        responseCode: number;
-        responseText: string;
-        responseXML: string;
-    }
-
-    /**
-     * <ul>
-     *     <li>status: status of the ajax cycle</li>
-     * </ul>
-     */
-    interface IEventData {
-        status: String;
-        source: any;
-    }
-
-    interface Ajax {
-        request(element: Element, event?: Event, options?: Options): void;
-        response(request: XMLHttpRequest, context?: Context): void;
-    }
-
-    interface Util {
-        chain(source, event, ...funcs: Array<Function | string>): boolean;
-    }
-
-    interface Push {
-        init(socketClientId: string,
-             uri: string,
-             channel: string,
-             onopen: Function,
-             onmessage: Function,
-             onclose: Function,
-             behaviorScripts: any,
-             autoconnect: boolean): void;
-        open(socketClientId: string);
-        close(socketClientId: string): void;
-    }
-
-    interface FacesAPI {
-        contextpath: string;
-        specversion: number;
-        implversion: number;
-        separatorchar: string;
-
-        getProjectStage(): string;
-        getViewState(formElement: Element | string): string;
-        getClientWindow(rootNode?: Element | string): string;
-        getSeparatorChar(): string;
-        response(request: XMLHttpRequest, context?: Context): void;
-        addOnError(errorFunc: (data: IErrorData) => void): void;
-        addOnEvent(eventFunc: (data: IEventData) => void): void;
-
-        ajax: Ajax;
-        util: Util;
-        push: Push;
-    }
-
-    interface OAM {
-        clearHiddenInput(formName: string, name: string): void;
-        setHiddenInput(formName: string, name: string, value: string): void;
-        submitForm(formName: string, linkId?: string |null, target?: string | null, params?: AssocArr<any> |Tuples<string, any> | null): boolean;
-    }
-
-    interface MyFacesAPI {
-        ab(source: Element, event: Event, eventName: string, execute: string, render: string, options?: Context, userParams?: Context): void;
-        reserveNamespace(namespace: string): void;
-
-        config: { [key: string]: any };
-        oam: OAM;
-        core: {
-            config ?: {[key: string]: any};
-        };
-    }
-
-
-
     /*
-     * Global namespaces type definitions
+     * Global namespace type definitions — typed from the canonical _api.ts source.
      */
-    let myfaces: MyFacesAPI;
-    let jsf: FacesAPI;
-    let faces: FacesAPI;
+    let faces: typeof faces;
+    let jsf: typeof faces;
+    let myfaces: typeof myfaces;
 
-    // special "magic", Typescript merges whatever we have
-    // to window. This is a language "hack", but documented.
     // see https://www.typescriptlang.org/docs/handbook/declaration-files/templates/global-modifying-module-d-ts.html
-    // lib.dom.d.ts declares the type Window as being type for window.
     // noinspection JSUnusedGlobalSymbols
     interface Window {
-        myfaces: MyFacesAPI,
-        faces: FacesAPI,
-        jsf: FacesAPI,
-        XMLHttpRequest: XMLHttpRequest,
-        called: { [key: string]: any }
+        [key: string]: any;
+        faces: typeof faces;
+        jsf: typeof faces;
+        myfaces: typeof myfaces;
+        XMLHttpRequest: XMLHttpRequest;
+        called: { [key: string]: any };
     }
 }
 
-// this is needed to tell the compiler that we have an ambient
-// module, otherwise the global overload would produce an error
-// https://www.typescriptlang.org/docs/handbook/declaration-files/templates/global-modifying-module-d-ts.html
-// noinspection JSUnusedGlobalSymbols
-export var __my_faces_ambient_module_glob_;
+// needed to make this file a module so the declare global block is valid
+export {};

package/{target/test/frameworkBase/_ext/monadish/fixtures/test2.js → src/main/typescript/@types/definitions/modules.d.ts}

@@ -13,5 +13,21 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-document.getElementById('id_1').innerHTML = "hello world";
-//# sourceMappingURL=test2.js.map
+// AI-generated: this file was created with assistance from Claude (Anthropic) — see AI_CONTRIBUTIONS.md
+
+declare module "mona-dish/dist/js/umd/index.js" {
+    export * from "mona-dish";
+}
+
+declare module "nise" {
+    const nise: any;
+    export = nise;
+}
+
+declare module "jsdom" {
+    export const JSDOM: any;
+    export const VirtualConsole: any;
+    export const CookieJar: any;
+    export const ResourceLoader: any;
+    export function toughCookie(...args: any[]): any;
+}