Add DescopeFlowHook for customizing how flow pages look and behave

[shilgapira]

Related Issues

Resolves https://github.com/descope/etc/issues/8778
Resolves https://github.com/descope/etc/issues/8541

Description

• Add the DescopeFlowHook class for customizing how flow pages look and behave, together with some built-in hooks to support most common use cases. See the documentation for more details and examples.

let flow = DescopeFlow(url: "https://example.com/myflow")
flow.hooks = [
    // use built-in hook that makes the flow page have a transparent background
    .setTransparentBody,

    // create hook that injects CSS that sets margins on the body element
    .addStyles(selector: "body", rules: [ "margin: 16px" ]),
]

• You can also create custom hooks in a DescopeFlowHook extension and give them descriptive names:

let flow = DescopeFlow(url: "https://example.com/myflow")
flow.hooks = [
    .setTransparentBody,
    .setBodyMargins,
    .disableScrolling,
    .removeFooter,
] 

extension DescopeFlowHook {
    // injects CSS that sets margins on the body element
    static let setBodyMargins = addStyles(selector: "body", rules: [ "margin: 16px" ]),

    // disables scrolling in the flow page
    static let disableScrolling = setupScrollView({ scrollView in
        scrollView.isScrollEnabled = false
    })

    // runs javascript that removes a footer element when the flow is ready
    static let removeFooter = runJavaScript(on: .ready, code: """
        const footer = document.querySelector('#footer')
        footer?.remove()
    """)
}

• Allow creating DescopeFlow objects with a plain String value instead of having to use ! on URL's optional initializer.

// now:
let flow = DescopeFlow(url: "https://example.com/myflow")

// instead of:
let flow = DescopeFlow(url: URL(string: "https://example.com/myflow")!)

Minor changes

• The DescopeFlowCoordinator class is now available when building for macOS.
• The DescopeFlowViewController class is now open for subclassing, and the createFlowView method can be overridden in subclasses to use a custom DescopeFlowView instance (consider using the new DescopeFlowHook feature instead of inheritance when possible).
• Moved the default native flow behaviors such as disabling zoom and the input accessory view to be implemented using hooks, and the developer can choose to override them using the counterpart enable* hooks.

Breaking changes

• In the DescopeFlowView class the prepareConfiguration and prepareWebView have been renamed (consider using the new DescopeFlowHook feature instead of inheritance when possible):
  • prepareConfiguration -> willCreateWebView
  • prepareWebView -> didCreateWebView
• In the DescopeFlowViewDelegate protocol the failure and success methods have been renamed to be consistent with the other delegates:
  • flowViewDidFailAuthentication -> flowViewDidFail
  • flowViewDidFinishAuthentication -> flowViewDidFinish

Must

• Tests
• Documentation (if applicable)