@rws-framework/client 2.3.1 → 2.4.2

package/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "MS-FAST"]
+	path = .fast
+	url = git@github.com:microsoft/fast.git

package/README.md

@@ -15,7 +15,8 @@ Realtime Web Suit is a web-component powered, MS FAST powered fullstack-oriented
 9. [Notifier](#notifier)
 10. [Service Worker](#service-worker)
 11. [Example: WebChat Component](#example-webchat-component)
-12. [Links](#links)
+12. [Other configs](#other-configs)
+13. [Links](#links)
 
 ## Overview
 
@@ -46,16 +47,21 @@ or to watch for dev
 ```bash
 yarn watch
 ```
+or to just start server
+```bash
+yarn server
+```
+
 then start engine in the site javascript (can be inline):
 
 ```javascript
-window.RWSClient.start(CFG).then();
+window.RWS.client.start(CFG); // it is async function
 ```
 
 *or for initial setup then start on certain event (example)* 
 
 ```javascript
-window.RWSClient.setup(CFG).then(() => {    
+window.RWS.client.setup(CFG).then(() => {     // it is async function
     $.on('loaded', function(data){
         const optionalNewCfg = { backendRoutes: data.backendRoutes };
         window.RWSClient.start(optionalNewCfg).then();
@@ -63,38 +69,86 @@ window.RWSClient.setup(CFG).then(() => {
 });
 ```
 
-example config with interface:
+### default config for RWS:
 
 ```javascript
-const CFG = {
-    backendUrl: 'http://localhost:1337',
-    wsUrl: 'http://localhost:1338',
-    transports: ['websocket'],
-    user: rwsUser,
-    parted: true,
-    splitFileDir: '/lib/rws',
-    splitPrefix: 'myapp'     
+const _DEFAULT_CONFIG_VARS = {
+    //Build configs
+    dev: false,
+    hot: false,
+    report: false,   
+    publicDir: './public',
+    publicIndex: 'index.html',      
+    outputFileName: 'client.rws.js',
+    outputDir: process.cwd() + '/build',
+    //Frontend RWS client configs  
+    backendUrl: null,
+    wsUrl: null,
+    partedDirUrlPrefix: '/lib/rws',
+    partedPrefix: 'rws',
+    pubUrlFilePrefix: '/',
+    //Universal configs
+    transports: ['websocket'],    
+    parted: false,        
+}
+
+```
+
+*The options description:*
+
+|  **Option**  | **Description** |  **Default**  |
+|--------------|-----------------|---------------|
+| backendUrl | Url for backend integration (API calls) | null |
+| wsUrl | Url for backend integration (Websocket calls) | null |
+| backendRoutes | Backend routes object imported from backend node for integration with API calls | null |
+| apiPrefix | Prefix for API calls | / |
+| routes | Routes for frontend routing | {} |
+| transports | Websockets transports method | ['websockets'] |
+| user | User object for backend auth / frontend data source | null |
+| ignoreRWSComponents | Do not declare base RWS components (uploader, progress) | false |
+| pubUrlFilePrefix | the url for accessing files from browser URL | / |
+| pubUrl | the url for accessing public dir from browser URL | / |
+| outputDir | build dir | ./build |
+| outputFileName | output file name | rws.client.js |
+| publicDir | public dir for HTML serving | ./public |
+| tsConfigPath | tsconfig.json path | ./tsconfig.njson |
+| entry | default TS entry for transpilation | ./src/index.ts |
+| parted | "Parted" mode if enabled. "Monolith" if disabled. Parted mode outputs every component as separate js file and asynchronously adds them to browser. Monolith is single file js build. | false |
+| partedPrefix | parted file prefix ([prefix].[cmp name].js) | rws |
+| partedDirUrlPrefix | URL for generated js parted files directory | / |
+| copyAssets | An option for defining structure that will be copied after build | {} |
+
+*copyAssets example*
+
+```json
+"copyAssets": {
+    "./public/js/": [ // target directory
+      "./build/", // copy this directory to target
+      "./src/styles/compiled/main.css" //copy this file to target
+    ]
 }
 ```
 
-### The FRONT config interface:
+### The FRONT config TS interface:
 
 ```typescript
 interface IRWSConfig {
     defaultLayout?: typeof RWSViewComponent
-    backendUrl?: string // url to backend request/response gateway
-    wsUrl?: string // url to backend websockets gateway
-     backendRoutes?: any[] // routes from backend
-    apiPrefix?: string // f.e /api after host
-    routes?: IFrontRoutes, //override front routes
-    transports?: string[], //ws transports setup
-    user?: any, //user data if logged
-    ignoreRWSComponents?: boolean //do not register base RWS components
-    pubUrl?: string //the url for accessing public dir from browser URL (default: /)
-    pubPrefix?: string 
-    parted?: boolean //sets async partitioning mode for components. Those wil be parted and loaded in BG.
-    splitFileDir?: string //the url for accessing split dir from browser URL (default: /)
-    splitPrefix?: string // prefix for parted file (`${pubPrefix}.${cmpName}.ts`)
+    backendUrl?: string
+    wsUrl?: string
+    backendRoutes?: any[]
+    apiPrefix?: string
+    routes?: IFrontRoutes
+    transports?: string[]
+    user?: any
+    ignoreRWSComponents?: boolean
+    pubUrl?: string
+    pubUrlFilePrefix?: string
+    partedDirUrlPrefix?: string
+    dontPushToSW?: boolean
+    parted?: boolean
+    partedFileDir?: string
+    partedPrefix?: string
     routing_enabled?: boolean
     _noLoad?: boolean    
 }
@@ -103,50 +157,18 @@ interface IRWSConfig {
 
 ```javascript
 const path = require('path');
-const fs = require('fs');
-const { spawn } = require('child_process');
-const CopyWebpackPlugin = require('copy-webpack-plugin');
-const RWSWebpackWrapper  = require('rws-js-client/rws.webpack.config');
-const { RuntimeGlobals } = require('webpack');
-
 
-const executionDir = process.cwd();
+const RWSWebpackWrapper  = require('@rws-framework/client/rws.webpack.config');
 
-const libdir = path.resolve(executionDir, '..', '..', 'target', 'app', 'lib', 'rws');
-const pubdir = path.resolve(executionDir, '..', '..', 'target', 'app');
 
-if(!fs.existsSync(libdir)){
-  fs.mkdirSync(libdir);
-}
-
-const copies = {
-  [libdir]: [
-    './build',
-    './src/styles/compiled/main.rws.css',
-  ],
-  [pubdir]: [
-    './public/service_worker.js',
-    './public/service_worker.js.map'
-  ]
-}
-
-const myappFrontPath = path.resolve(__dirname, '../myapp/frontend');
+const executionDir = process.cwd();
 
-module.exports = RWSWebpackWrapper({
-  dev: true,
-  hot: false,
+module.exports = RWSWebpackWrapper({  
   tsConfigPath: executionDir + '/tsconfig.json',
-  entry: `${executionDir}/src/index.ts`,
-  executionDir: executionDir,
+  entry: `${executionDir}/src/index.ts`,  
   publicDir:  path.resolve(executionDir, 'public'),
   outputDir:  path.resolve(executionDir, 'build'),
-  outputFileName: 'junction.client.js',
-  copyToDir: copies,
-  serviceWorker: './src/service_worker/MyServiceWorker.ts',
-  parted: true,
-  partedPrefix: 'myapp',
-  partedComponentsLocations: ['../myapp', './src'],
-  customServiceLocations: ['${myappFrontPath}/src/services']
+  outputFileName: 'jtrainer.client.js'
 });
 ```
 
@@ -156,13 +178,28 @@ module.exports = RWSWebpackWrapper({
 
 ### RWSClient
 ##
-`RWSClient` is the heart of the framework, managing configuration and initialization. It sets up routes, backend connections, and other essential framework services.
+`RWS.client` is the heart of the framework, managing configuration and initialization. It sets up routes, backend connections, and other essential framework services.
 
 
 ### RoutingService
-##
+
 `RoutingService` handles the navigation and routing within your application. It ensures that URL changes reflect the correct component rendering.
 
+**Depreciation Notice**
+
+***RoutingService will be moved to @rws-framework/browser-router near future***
+
+### WSService
+
+`WSService` handles Websockets messenging to the backend.
+
+**Depreciation Notice**
+***WSService will be moved to @rws-framework/nest-interconnectors in near future***
+
+### APIService
+
+`APIService` handles API requests to the backend.
+
 Implementing the Framework
 
 **Main File:**
@@ -172,66 +209,85 @@ The main file (`index.ts`) is where you initialize the RWSClient. Here, you conf
 Following is example of full usage of the framework
 
 ```typescript
-import RWSClient, { NotifyUiType, NotifyLogType } from '@rws-framework/client';
-//@ts-ignore
-import alertify from 'alertifyjs';
+async function initializeApp() {           
+    const theClient = RWSContainer().get(RWSClient);    
 
-import './styles/main.rws.scss';
-import { backendRoutes } from './backendImport';
-import { provideFASTDesignSystem, allComponents } from '@microsoft/fast-components';
-
-// For single file output (will inject itself to DI on import):
-//import initComponents from './application/_initComponents'
-
-async function initializeApp() {       
-    const theClient = RWSContainer().get(RWSClient);
-    
+    theClient.addRoutes(frontendRoutes);
     theClient.setBackendRoutes(backendRoutes());
+
+    theClient.enableRouting();
     
     theClient.onInit(async () => {        
 
         // For single file output:
-        //initComponents();
-
-        provideFASTDesignSystem().register(allComponents);
-
+        initComponents(theClient.appConfig.get('parted'));  // start components for monolith mode      
+        theClient.defineComponents(); // start RWS conponents
+
+        //custom outside components registering
+        provideFASTDesignSystem()
+            .register(fastButton())
+            .register(fastTab())
+            .register(fastSlider())
+            .register(fastSelect())
+            .register(fastDivider())
+            .register(fastMenu())
+            .register(fastMenuItem())
+        ;
+
+        // Service worker code
         // const swFilePath: string = `${theClient.appConfig.get('pubUrl')}/service_worker.js`;          
 
-        await theClient.swService.registerServiceWorker();        
+        // await theClient.swService.registerServiceWorker();        
 
-        if(theClient.getUser()){
-            theClient.pushUserToServiceWorker({...theClient.getUser(), instructor: false});  
-        }
+        //if(theClient.getUser()){
+            // theClient.pushUserToServiceWorker({...theClient.getUser(), instructor: false});  
+        //}
 
     });
 
-    theClient.setNotifier((message: string, logType: NotifyLogType, uiType: NotifyUiType = 'notification', onConfirm: (params: any) => void) => {
+    theClient.setNotifier((message: string, logType: NotifyLogType, uiType: NotifyUiType = 'notification', onConfirm: (params: any) => void, notifierOptions: any = {}) => {
         switch(uiType){
-            case 'notification':
-                let notifType = 'success';
+        case 'notification':
+            let notifType = 'success';
 
-                if(logType === 'error'){
-                    notifType = 'error';
-                }
+            if(logType === 'error'){
+                notifType = 'error';
+            }
+
+            if(logType === 'warning'){
+                notifType = 'warning';
+            }
 
-                if(logType === 'warning'){
-                    notifType = 'warning';
+            return alertify.notify(message, notifType, 5, onConfirm);
+               
+        case 'alert':                
+            const alertObj = alertify.alert('Junction AI Notification', message, onConfirm);
+
+            Object.keys(notifierOptions).forEach(key => {
+                const optionValue = notifierOptions[key];
+
+                if(key === 'width'){
+                    
+                    alertObj.elements.dialog.style = `max-width: ${optionValue};`;
+                    
+                    return;
                 }
 
-                alertify.notify(message, notifType, 5, onConfirm);
-                return;
-            case 'alert':
-                alertify.alert('Junction AI Notification', message, onConfirm);
-                return;    
-            case 'silent':
-                if(logType == 'warning'){
-                    console.warn(message);
-                }else if(logType == 'error'){
-                    console.error(message);
-                }else{
-                    console.log(message);
-                }            
-                return;    
+                alertObj.set(key, optionValue);
+            });
+
+            alertObj.show();
+
+            return alertObj;    
+        case 'silent':
+            if(logType == 'warning'){
+                console.warn(message);
+            }else if(logType == 'error'){
+                console.error(message);
+            }else{
+                console.log(message);
+            }            
+            return;    
         }
     });
     
@@ -245,6 +301,8 @@ initializeApp().catch(console.error);
 
 In `application/_initComponents.ts`, you initialize the custom components used in your application. If components added in here will include other components they dont need to be listed here. A component imported in this mode needs to be imported once.
 
+**This should be conditioned not to execute imported code when using parted mode.**
+
 ### Default component structure
 
 ```
@@ -292,41 +350,21 @@ component-dir/
 Only if parted mode is false.
 
 ```typescript
-import jTrainerComponents from '../../../jtrainer/frontend/src/application/_initComponents';
-
-import { WebChat } from '../../../jtrainer/frontend/src/components/webchat/component';
-import { JunctionTrainer } from '../../../jtrainer/frontend/src/components/trainer/component';
-
-import { BookLoader } from '../components/book-loader/component'
-import { ChatLoader } from '../components/chat-loader/component'
-
-import { registerRWSComponents } from '@rws-framework/client';
-
-export default () => {
-    jTrainerComponents();
-    WebChat;
-    JunctionTrainer;
-    BookLoader;    
-    ChatLoader;
-
-    RWSClientInstance.defineAllComponents();
-}
-
-```
-
-```typescript
-//index.ts
-
- const theClient = new RWSClient();
-
-    
-    theClient.addRoutes(routes);    //routes are optional
-    
-    theClient.onInit(async () => {
-        initComponents(); //user components from _initComponents.ts (dont run and import when parted: true)
-        provideFASTDesignSystem().register(allComponents); // @microsoft/fast-components ready components init
-    });    
-
+import { ChatNav } from '../components/chat-nav/component';
+import { DefaultLayout } from '../components/default-layout/component';
+import { RWSIcon } from '../components/rws-icon/component';
+import { LineSplitter } from '../components/line-splitter/component';
+import { WebChat } from '../components/webchat/component';
+
+export default (partedMode: boolean = false) => {
+    if(!partedMode){
+        WebChat;
+        LineSplitter;
+        DefaultLayout;
+        ChatNav;
+        RWSIcon;        
+    }
+};
 ```
 
 **Component needs to extend RWSViewComponent and use @RWSView decorator**:
@@ -379,12 +417,8 @@ Default services: https://github.com/papablack/rws-client/blob/7d16d9c6d83c81c9f
 
 ```typescript
 import { 
-    NotifyService, RWSView, RWSViewComponent, 
-    WSService, ApiService, ConfigService, 
-    ConfigServiceInstance, UtilsServiceInstance, ApiServiceInstance, 
-    UtilsService, DOMServiceInstance, DOMService, 
-    NotifyServiceInstance, WSServiceInstance, RoutingService, 
-    RoutingServiceInstance, RWSInject
+    RWSView, RWSViewComponent, RWSInject,
+    DateService, DateServiceInstance
 } from 'rws-js-client';
 
 import DateService, {DateServiceInstance} from '../../my-custom-services/DateService';
@@ -392,18 +426,14 @@ import DateService, {DateServiceInstance} from '../../my-custom-services/DateSer
 
 @RWSView('your-tag')
 class YourComponent extends RWSViewComponent {
+    //usage in props:
+    private @RWSInject(ServiceFASTDIPointer) serviceProperty: ServiceClassType; 
+
+    //usage in constructor:
     constructor(
-        @RWSInject(DateService) protected dateService: DateServiceInstance, //custom service - default services from RWSViewComponent below
-        @RWSInject(ConfigService) protected config: ConfigServiceInstance,
-        @RWSInject(RoutingService) protected routingService: RoutingServiceInstance,
-        @RWSInject(DOMService) protected domService: DOMServiceInstance,
-        @RWSInject(UtilsService) protected utilsService: UtilsServiceInstance,
-        @RWSInject(ApiService) protected apiService: ApiServiceInstance,
-        @RWSInject(WSService) protected wsService: WSServiceInstance,
-        @RWSInject(NotifyService) protected notifyService: NotifyServiceInstance
+        private @RWSInject(DateService) protected dateService: DateServiceInstance
     ) {
-        super(config, routingService, domService, utilsService, apiService, wsService, notifyService);
-        applyConstructor(this);   //fix-incoming: DI constructor data inheritance problem - applyConstructor in super is bugged. Need tmp workaround.
+        super();
     }
 
     someMethod(url: string): void
@@ -414,6 +444,20 @@ class YourComponent extends RWSViewComponent {
  
 ```
 
+Custom service needs to export .getSingleton() as default export and have service class exported as classic export for TS typing:
+
+```typescript
+import { RWSService } from '@rws-framework/client';
+
+
+class DateService extends RWSService {
+    //(...)
+}
+
+export default DateService.getSingleton(); // Fast DI service pointer (it points to instanced service in DI container)
+export { DateService as DateServiceInstance }; // the custom service class type
+```
+
 ## Frontend routes
 
 if you are passing routes this is example routing file for frontend:
@@ -525,14 +569,6 @@ Ensure that a notifier is set in the RWS Client to use the `NotifyService` effec
 
 If you pass ```{serviceWorker: 'service_worker_class_path.ts'}``` to RWS Webpack wrapper function param, the code will build ServiceWorker to pubDir.
 
-**Remember to have lib field set in tesconfig.json**
-
-```json
-{
- "lib": ["DOM", "ESNext", "WebWorker"]
-}
-```
-
 example ServiceWorker class:
 
 ```typescript
@@ -662,6 +698,8 @@ class MyServiceWorker extends RWSServiceWorker {
 MyServiceWorker.create();
 ```
 
+**We point to this file in webpack / .rws.json "service_worker" option**
+
 ## Example: WebChat Component
 
 The WebChat component demonstrates a practical use of `APIService` in a real-world scenario. It shows how to send and receive data from the backend.
@@ -916,6 +954,47 @@ are defined in backend/src/config/config
     }
 ```
 
-## Links
+## Other configs
+
+### example tsconfig.json
+
+```json
+{
+    "compilerOptions": {
+      "baseUrl": "../",
+      "experimentalDecorators": true,
+      "emitDecoratorMetadata": true,
+      "target": "ES2018",
+      "module": "es2022",       
+      "moduleResolution": "node",     
+      "strict": true,
+      "esModuleInterop": true,
+      "sourceMap": true,
+      "outDir": "dist",
+      "strictNullChecks": false,    
+      "allowSyntheticDefaultImports": true,    
+      "lib": ["DOM", "ESNext", "WebWorker"], 
+      "paths": {        
+      }       
+    },
+    "include": [
+      "src",          
+      "../node_modules/@rws-framework/client/declarations.d.ts", //TEMPORARILY NEEDED TO WORK
+    ],  
+    "exclude": [
+      "../node_modules/@rws-framework/client/src/tests"    
+    ]
+  }
+```
+
+**Remember to have lib field set in tsconfig.json**
 
+```json
+{
+ "lib": ["DOM", "ESNext"]
+}
+```
+
+## Links
+- https://www.fast.design/docs/fast-element/getting-started ( Base FAST documentation, mostly valid not considering passing styles and templates as RWS handles it with Webpack loaders )
 - https://www.webcomponents.org (open-source WebComponents repository)

package/cfg/_default.cfg.js

@@ -10,7 +10,7 @@ const _DEFAULT_CONFIG_VARS = {
     //Frontend RWS client configs  
     backendUrl: null,
     wsUrl: null,
-    partedDirUrlPrefix: '/lib/rws',
+    partedDirUrlPrefix: '/',
     partedPrefix: 'rws',
     pubUrlFilePrefix: '/',
     //Universal configs

package/console.js

@@ -77,7 +77,7 @@ async function buildSwCmd(){
   
   try {
     console.log(chalk.yellow('[RWS Client]'), 'Installing service worker...');
-    await tools.runCommand(`${webpackCmd} --config ${path.resolve(moduleDir,'src','service_worker')}/webpack.config.js`, executionDir, false, { env: { SWPATH: firstArg } });
+    await tools.runCommand(`${webpackCmd} --config ${path.resolve(moduleDir, 'service_worker')}/webpack.config.js`, executionDir, false, { env: { SWPATH: firstArg } });
     console.log(chalk.green('[RWS Client]'), 'Service worker installed.');
   }catch(e){
     console.error('runerror',e);

package/docs/assets/highlight.css

@@ -9,24 +9,26 @@
     --dark-hl-3: #9CDCFE;
     --light-hl-4: #0070C1;
     --dark-hl-4: #4FC1FF;
-    --light-hl-5: #0000FF;
-    --dark-hl-5: #569CD6;
-    --light-hl-6: #AF00DB;
-    --dark-hl-6: #C586C0;
-    --light-hl-7: #267F99;
-    --dark-hl-7: #4EC9B0;
-    --light-hl-8: #008000;
-    --dark-hl-8: #6A9955;
-    --light-hl-9: #098658;
-    --dark-hl-9: #B5CEA8;
-    --light-hl-10: #800000;
-    --dark-hl-10: #808080;
+    --light-hl-5: #008000;
+    --dark-hl-5: #6A9955;
+    --light-hl-6: #0000FF;
+    --dark-hl-6: #569CD6;
+    --light-hl-7: #0451A5;
+    --dark-hl-7: #9CDCFE;
+    --light-hl-8: #267F99;
+    --dark-hl-8: #4EC9B0;
+    --light-hl-9: #AF00DB;
+    --dark-hl-9: #C586C0;
+    --light-hl-10: #098658;
+    --dark-hl-10: #B5CEA8;
     --light-hl-11: #800000;
-    --dark-hl-11: #569CD6;
-    --light-hl-12: #E50000;
-    --dark-hl-12: #9CDCFE;
-    --light-hl-13: #0000FF;
-    --dark-hl-13: #CE9178;
+    --dark-hl-11: #808080;
+    --light-hl-12: #800000;
+    --dark-hl-12: #569CD6;
+    --light-hl-13: #E50000;
+    --dark-hl-13: #9CDCFE;
+    --light-hl-14: #0000FF;
+    --dark-hl-14: #CE9178;
     --light-code-background: #FFFFFF;
     --dark-code-background: #1E1E1E;
 }
@@ -46,6 +48,7 @@
     --hl-11: var(--light-hl-11);
     --hl-12: var(--light-hl-12);
     --hl-13: var(--light-hl-13);
+    --hl-14: var(--light-hl-14);
     --code-background: var(--light-code-background);
 } }
 
@@ -64,6 +67,7 @@
     --hl-11: var(--dark-hl-11);
     --hl-12: var(--dark-hl-12);
     --hl-13: var(--dark-hl-13);
+    --hl-14: var(--dark-hl-14);
     --code-background: var(--dark-code-background);
 } }
 
@@ -82,6 +86,7 @@
     --hl-11: var(--light-hl-11);
     --hl-12: var(--light-hl-12);
     --hl-13: var(--light-hl-13);
+    --hl-14: var(--light-hl-14);
     --code-background: var(--light-code-background);
 }
 
@@ -100,6 +105,7 @@
     --hl-11: var(--dark-hl-11);
     --hl-12: var(--dark-hl-12);
     --hl-13: var(--dark-hl-13);
+    --hl-14: var(--dark-hl-14);
     --code-background: var(--dark-code-background);
 }
 
@@ -117,4 +123,5 @@
 .hl-11 { color: var(--hl-11); }
 .hl-12 { color: var(--hl-12); }
 .hl-13 { color: var(--hl-13); }
+.hl-14 { color: var(--hl-14); }
 pre, code { background: var(--code-background); }