update readme & sdks

packages/sdks/angular-sdk/README.md

@@ -203,6 +203,37 @@ export class AppComponent {
 ></descope>
 ```
 
+### `onScreenUpdate`
+
+A function that is called whenever there is a new screen state and after every next call. It receives the following parameters:
+
+- `screenName`: The name of the screen that is about to be rendered
+- `state`: An object containing the upcoming screen state
+- `next`: A function that, when called, continues the flow execution
+- `ref`: A reference to the descope-wc node
+
+The function can be sync or async, and should return a boolean indicating whether a custom screen should be rendered:
+
+- `true`: Render a custom screen
+- `false`: Render the default flow screen
+
+This function allows rendering custom screens instead of the default flow screens.
+It can be useful for highly customized UIs or specific logic not covered by the default screens
+
+To render a custom screen, its elements should be appended as children of the `descope` component
+
+Usage example:
+
+```javascript
+function onScreenUpdate(screenName, state, next, ref) {
+  if (screenName === 'My Custom Screen') {
+    return true;
+  }
+
+  return false;
+}
+```
+
 #### Standalone Mode
 
 All components in the sdk are standalone, so you can use them by directly importing them to your components.

packages/sdks/angular-sdk/projects/angular-sdk/src/lib/components/descope/descope.component.spec.ts

@@ -62,6 +62,7 @@ describe('DescopeComponent', () => {
       debug: jest.fn()
     };
     component.errorTransformer = jest.fn();
+    component.onScreenUpdate = jest.fn();
     component.client = {};
     component.form = {};
     component.storeLastAuthenticatedUser = true;

packages/sdks/angular-sdk/projects/angular-sdk/src/lib/components/descope/descope.component.ts

@@ -38,6 +38,15 @@ export class DescopeComponent implements OnInit, OnChanges {
 
   @Input() debug: boolean;
   @Input() errorTransformer: (error: { text: string; type: string }) => string;
+  @Input() onScreenUpdate: (
+    screenName: string,
+    state: Record<string, any>,
+    next: (
+      interactionId: string,
+      form: Record<string, any>
+    ) => Promise<unknown>,
+    ref: HTMLElement
+  ) => boolean | Promise<boolean>;
   @Input() client: Record<string, any>;
   @Input() form: Record<string, any>;
   @Input() logger: ILogger;
@@ -155,6 +164,10 @@ export class DescopeComponent implements OnInit, OnChanges {
       this.webComponent.errorTransformer = this.errorTransformer;
     }
 
+    if (this.onScreenUpdate) {
+      this.webComponent.onScreenUpdate = this.onScreenUpdate;
+    }
+
     if (this.client) {
       this.webComponent.setAttribute('client', JSON.stringify(this.client));
     }

packages/sdks/angular-sdk/projects/angular-sdk/src/lib/components/sign-in-flow/sign-in-flow.component.html

@@ -12,6 +12,7 @@
   [restartOnError]="restartOnError"
   [debug]="debug"
   [errorTransformer]="errorTransformer"
+  [onScreenUpdate]="onScreenUpdate"
   [client]="client"
   [form]="form"
   [logger]="logger"

packages/sdks/angular-sdk/projects/angular-sdk/src/lib/components/sign-in-flow/sign-in-flow.component.ts

@@ -20,9 +20,18 @@ export class SignInFlowComponent {
   @Input() autoFocus: true | false | 'skipFirstScreen';
   @Input() validateOnBlur: boolean;
   @Input() restartOnError: boolean;
-  
+
   @Input() debug: boolean;
   @Input() errorTransformer: (error: { text: string; type: string }) => string;
+  @Input() onScreenUpdate: (
+    screenName: string,
+    state: Record<string, any>,
+    next: (
+      interactionId: string,
+      form: Record<string, any>
+    ) => Promise<unknown>,
+    ref: HTMLElement
+  ) => boolean | Promise<boolean>;
   @Input() client: Record<string, any>;
   @Input() form: Record<string, any>;
   @Input() logger: ILogger;

packages/sdks/angular-sdk/projects/angular-sdk/src/lib/components/sign-up-flow/sign-up-flow.component.html

@@ -12,6 +12,7 @@
   [restartOnError]="restartOnError"
   [debug]="debug"
   [errorTransformer]="errorTransformer"
+  [onScreenUpdate]="onScreenUpdate"
   [client]="client"
   [form]="form"
   [logger]="logger"

packages/sdks/angular-sdk/projects/angular-sdk/src/lib/components/sign-up-flow/sign-up-flow.component.ts

@@ -20,9 +20,18 @@ export class SignUpFlowComponent {
   @Input() autoFocus: true | false | 'skipFirstScreen';
   @Input() validateOnBlur: boolean;
   @Input() restartOnError: boolean;
-  
+
   @Input() debug: boolean;
   @Input() errorTransformer: (error: { text: string; type: string }) => string;
+  @Input() onScreenUpdate: (
+    screenName: string,
+    state: Record<string, any>,
+    next: (
+      interactionId: string,
+      form: Record<string, any>
+    ) => Promise<unknown>,
+    ref: HTMLElement
+  ) => boolean | Promise<boolean>;
   @Input() client: Record<string, any>;
   @Input() form: Record<string, any>;
   @Input() logger: ILogger;

packages/sdks/angular-sdk/projects/angular-sdk/src/lib/components/sign-up-or-in-flow/sign-up-or-in-flow.component.html

@@ -12,6 +12,7 @@
   [restartOnError]="restartOnError"
   [debug]="debug"
   [errorTransformer]="errorTransformer"
+  [onScreenUpdate]="onScreenUpdate"
   [client]="client"
   [form]="form"
   [logger]="logger"

packages/sdks/angular-sdk/projects/angular-sdk/src/lib/components/sign-up-or-in-flow/sign-up-or-in-flow.component.ts

@@ -20,9 +20,18 @@ export class SignUpOrInFlowComponent {
   @Input() autoFocus: true | false | 'skipFirstScreen';
   @Input() validateOnBlur: boolean;
   @Input() restartOnError: boolean;
-  
+
   @Input() debug: boolean;
   @Input() errorTransformer: (error: { text: string; type: string }) => string;
+  @Input() onScreenUpdate: (
+    screenName: string,
+    state: Record<string, any>,
+    next: (
+      interactionId: string,
+      form: Record<string, any>
+    ) => Promise<unknown>,
+    ref: HTMLElement
+  ) => boolean | Promise<boolean>;
   @Input() client: Record<string, any>;
   @Input() form: Record<string, any>;
   @Input() logger: ILogger;

packages/sdks/react-sdk/README.md

@@ -166,6 +166,75 @@ const App = () => {
 }
 ```
 
+### `onScreenUpdate`
+
+A function that is called whenever there is a new screen state and after every next call. It receives the following parameters:
+
+- `screenName`: The name of the screen that is about to be rendered
+- `state`: An object containing the upcoming screen state
+- `next`: A function that, when called, continues the flow execution
+- `ref`: A reference to the descope-wc node
+
+The function can be sync or async, and should return a boolean indicating whether a custom screen should be rendered:
+
+- `true`: Render a custom screen
+- `false`: Render the default flow screen
+
+This function allows rendering custom screens instead of the default flow screens.
+It can be useful for highly customized UIs or specific logic not covered by the default screens
+
+To render a custom screen, its elements should be appended as children of the `Descope` component
+
+Usage example:
+
+```javascript
+const CustomScreen = ({onClick, setForm}) => {
+  const onChange = (e) => setForm({ email: e.target.value })
+
+  return (
+    <>
+      <input 
+        type="email" 
+        placeholder="Email" 
+        onChange={onChange}
+      />
+      <button
+        type="button"
+        onClick={onClick}
+      >
+        Submit
+      </button>
+    </>
+)}
+
+const Login = () => {
+  const [state, setState] = useState();
+  const [form, setForm] = useState();
+
+  const onScreenUpdate = (screenName, state, next) => {
+    setState({screenName, state, next})
+
+    if (screenName === 'My Custom Screen') {
+      return true;
+    }
+
+    return false;
+  };
+
+  return <Descope
+  ...
+  onScreenUpdate={onScreenUpdate}
+  >{state.screenName === 'My Custom Screen' && <CustomScreen 
+    onClick={() => {
+      // replace with the button interaction id
+      next('interactionId', form)
+    }} 
+    setForm={setForm}/>}
+  </Descope>
+}
+
+```
+
 ### Use the `useDescope`, `useSession` and `useUser` hooks in your components in order to get authentication state, user details and utilities
 
 This can be helpful to implement application-specific logic. Examples:

packages/sdks/react-sdk/src/types.ts

@@ -136,7 +136,7 @@ export type DescopeProps = {
       form: Record<string, any>,
     ) => Promise<unknown>,
     ref: HTMLElement,
-  ) => boolean;
+  ) => boolean | Promise<boolean>;
   children?: React.ReactNode;
 };
 

packages/sdks/vue-sdk/README.md

@@ -87,6 +87,39 @@ const handleReady = () => {
 </script>
 ```
 
+
+### `onScreenUpdate`
+
+A function that is called whenever there is a new screen state and after every next call. It receives the following parameters:
+
+- `screenName`: The name of the screen that is about to be rendered
+- `state`: An object containing the upcoming screen state
+- `next`: A function that, when called, continues the flow execution
+- `ref`: A reference to the descope-wc node
+
+The function can be sync or async, and should return a boolean indicating whether a custom screen should be rendered:
+
+- `true`: Render a custom screen
+- `false`: Render the default flow screen
+
+This function allows rendering custom screens instead of the default flow screens.
+It can be useful for highly customized UIs or specific logic not covered by the default screens
+
+To render a custom screen, its elements should be appended as children of the `Descope` component
+
+Usage example:
+
+```javascript
+function onScreenUpdate(screenName, state, next) {
+  if (screenName === 'My Custom Screen') {
+    return true;
+  }
+
+  return false;
+}
+```
+
+
 ### Use the `useDescope`, `useSession` and `useUser` functions in your components in order to get authentication state, user details and utilities
 
 This can be helpful to implement application-specific logic. Examples:

packages/sdks/vue-sdk/example/components/Login.vue

@@ -11,9 +11,11 @@
       @error="handleError"
       @ready="handleReady"
       :errorTransformer="errorTransformer"
+      :onScreenUpdate="onScreenUpdate"
       :form="form"
       :client="client"
-    />
+    >
+    </Descope>
   </div>
 </template>
 
@@ -44,6 +46,12 @@ const errorTransformer = (error) => {
   return translationMap[error.type] || error.text;
 };
 
+const onScreenUpdate = (screenName, state, next) => {
+  console.log('Screen update', screenName, state, next);
+
+  return false;
+};
+
 const { isLoading, isAuthenticated } = useSession();
 const flowId = process.env.VUE_APP_DESCOPE_FLOW_ID || 'sign-up-or-in';
 const form = {}; // { email: '[email protected]' }; // found in context key: form.email

packages/sdks/vue-sdk/src/Descope.vue

@@ -19,12 +19,15 @@
       :restart-on-error="restartOnError"
       :store-last-authenticated-user="storeLastAuthenticatedUser"
       :errorTransformer.prop="errorTransformer"
+      :onScreenUpdate.prop="onScreenUpdate"
       :form.attr="formStr"
       :client.attr="clientStr"
       @success="onSuccess"
       @error="onError"
       @ready="onReady"
-    />
+    >
+    <slot></slot>
+  </descope-wc>
   </div>
 </template>
 
@@ -95,6 +98,9 @@ const props = defineProps({
   errorTransformer: {
     type: Function,
   },
+  onScreenUpdate: {
+    type: Function,
+  },
   form: {
     type: Object,
   },

packages/sdks/vue-sdk/tests/Descope.test.ts

@@ -23,6 +23,7 @@ describe('Descope.vue', () => {
     const errorTransformer = (error: { text: string; type: string }) => {
       return error.text || error.type;
     };
+    const onScreenUpdate = () => false;
     const wrapper = mount(Descope, {
       props: {
         flowId: 'test-flow-id',
@@ -34,6 +35,7 @@ describe('Descope.vue', () => {
         redirectUrl: 'test-redirect-url',
         autoFocus: true,
         errorTransformer,
+        onScreenUpdate,
         form: { test: 'a' },
         client: { test: 'b' },
         styleId: 'test-style-id',
@@ -53,6 +55,7 @@ describe('Descope.vue', () => {
     expect(descopeWc.attributes('redirect-url')).toBe('test-redirect-url');
     expect(descopeWc.attributes('auto-focus')).toBe('true');
     expect(wrapper.vm.errorTransformer).toBe(errorTransformer);
+    expect(wrapper.vm.onScreenUpdate).toBe(onScreenUpdate);
     expect(descopeWc.attributes('form')).toBe('{"test":"a"}');
     expect(wrapper.vm.client).toStrictEqual({ test: 'b' });
     expect(descopeWc.attributes('style-id')).toBe('test-style-id');
@@ -61,14 +64,15 @@ describe('Descope.vue', () => {
   it('renders a DescopeWc component with empty props', () => {
     const wrapper = mount(Descope, {
       props: {
-        form: null,
-        client: null,
+        flowId: 'test-flow-id',
+        form: {},
+        client: {},
       },
     });
 
     const descopeWc = wrapper.find('descope-wc');
-    expect(descopeWc.attributes('form')).toBe('');
-    expect(wrapper.vm.client).toBeNull();
+    expect(descopeWc.attributes('form')).toEqual('{}');
+    expect(wrapper.vm.client).toEqual({});
   });
 
   it('init sdk config', async () => {