@owlmeans/web-flow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,411 @@
+# @owlmeans/web-flow
+
+Web-specific flow management library for OwlMeans Common applications. This package extends `@owlmeans/client-flow` with web browser-specific functionality including URL-based flow state management, browser navigation integration, and query parameter handling.
+
+## Overview
+
+The `@owlmeans/web-flow` package provides web-specific implementations of the OwlMeans flow system. It offers:
+
+- **URL-Based Flow State**: Flow state management through browser URLs and query parameters
+- **Browser Navigation**: Integration with browser history and navigation APIs
+- **Resource Persistence**: Web-specific flow state persistence using browser storage
+- **Query Parameter Management**: Automatic flow state serialization in URL parameters
+- **Module Integration**: Enhanced module integration for web-based flow transitions
+- **Client-Side Routing**: Seamless integration with React Router for flow navigation
+
+This package is part of the OwlMeans flow management quadra:
+- **@owlmeans/flow**: Common flow interfaces and utilities
+- **@owlmeans/client-flow**: Client-side flow implementation
+- **@owlmeans/web-flow**: Web-specific flow implementation *(this package)*
+- **@owlmeans/server-flow**: Server-side flow processing
+
+## Installation
+
+```bash
+npm install @owlmeans/web-flow react react-router-dom
+```
+
+## Core Concepts
+
+### Web Flow Service
+Extends the basic flow service with web-specific capabilities like URL management and browser navigation.
+
+### URL State Management
+Flow state is automatically serialized and stored in URL query parameters, allowing flows to survive page reloads and be shareable.
+
+### Browser Integration
+Full integration with browser APIs for navigation, history management, and URL manipulation.
+
+## API Reference
+
+### Factory Functions
+
+#### `makeFlowService(alias?: string): FlowService`
+
+Creates a web-specific flow service with enhanced browser integration.
+
+```typescript
+import { makeFlowService } from '@owlmeans/web-flow'
+
+const webFlowService = makeFlowService('web-flow')
+```
+
+**Parameters:**
+- `alias`: string (optional) - Service alias for registration, defaults to 'flow'
+
+**Returns:** Enhanced FlowService with web-specific capabilities
+
+#### `appendWebFlowService<C, T>(context: T, alias?: string): T`
+
+Appends a web flow service to the application context with necessary resource setup.
+
+```typescript
+import { appendWebFlowService } from '@owlmeans/web-flow'
+import { makeClientContext } from '@owlmeans/client-context'
+
+const context = makeClientContext(config)
+appendWebFlowService(context)
+```
+
+**Parameters:**
+- `context`: T - The client context to append the service to
+- `alias`: string (optional) - Service alias, defaults to 'flow'
+
+**Returns:** Enhanced context with web flow service and resources
+
+### Enhanced Methods
+
+#### `proceed(req?: Partial<AbstractRequest>, dryRun?: boolean): Promise<string>`
+
+Web-specific implementation of flow progression with URL management.
+
+**Behavior**:
+- Calls the appropriate module for the current flow step
+- Serializes flow state into URL query parameters
+- Handles browser navigation and URL updates
+- Integrates with React Router for seamless transitions
+
+**Usage**: Advancing through flow steps with automatic URL updates
+
+```typescript
+const webFlowService = context.service<FlowService>('flow')
+
+// Proceed to next step with automatic URL update
+await webFlowService.proceed({
+  body: { userInput: 'data' }
+})
+```
+
+### Configuration
+
+#### Flow Configuration Options
+
+```typescript
+interface WebFlowConfig extends FlowConfig {
+  queryParam?: string    // URL query parameter name for flow state
+}
+```
+
+### Constants
+
+#### `QUERY_PARAM`
+Default query parameter name for flow state (`'flow'`).
+
+## Usage Examples
+
+### Basic Web Flow Setup
+
+```typescript
+import { appendWebFlowService } from '@owlmeans/web-flow'
+import { makeClientContext } from '@owlmeans/client-context'
+
+// Create context with web flow
+const context = makeClientContext({
+  service: 'my-web-app',
+  flowConfig: {
+    defaultFlow: 'user-onboarding',
+    queryParam: 'state'  // Custom query parameter name
+  }
+})
+
+appendWebFlowService(context)
+
+// Initialize
+await context.configure().init()
+```
+
+### URL-Aware Flow Component
+
+```typescript
+import { useContext } from '@owlmeans/client'
+import { useSearchParams } from 'react-router-dom'
+import { useEffect, useState } from 'react'
+
+function WebFlowComponent() {
+  const context = useContext()
+  const [searchParams] = useSearchParams()
+  const [currentStep, setCurrentStep] = useState(null)
+  
+  useEffect(() => {
+    const initFlow = async () => {
+      const flowService = context.service('flow')
+      
+      // Check if flow state exists in URL
+      const flowState = searchParams.get('flow')
+      let flow
+      
+      if (flowState) {
+        // Restore flow from URL parameter
+        flow = await flowService.load(flowState)
+      } else {
+        // Start new flow
+        flow = await flowService.begin('user-onboarding')
+      }
+      
+      setCurrentStep(flow.step())
+    }
+    
+    initFlow()
+  }, [searchParams])
+  
+  const handleNext = async () => {
+    const flowService = context.service('flow')
+    await flowService.proceed({ action: 'next' })
+    
+    // Flow state is automatically updated in URL
+    const updatedFlow = await flowService.state()
+    setCurrentStep(updatedFlow?.step())
+  }
+  
+  return (
+    <div>
+      <h2>Current Step: {currentStep}</h2>
+      <button onClick={handleNext}>Next Step</button>
+    </div>
+  )
+}
+```
+
+### Shareable Flow URLs
+
+```typescript
+function ShareableFlow() {
+  const context = useContext()
+  
+  const getShareableURL = async () => {
+    const flowService = context.service('flow')
+    const flow = await flowService.state()
+    
+    if (flow) {
+      const currentURL = new URL(window.location.href)
+      currentURL.searchParams.set('flow', flow.serialize())
+      return currentURL.toString()
+    }
+    
+    return window.location.href
+  }
+  
+  const handleShare = async () => {
+    const shareableURL = await getShareableURL()
+    
+    if (navigator.share) {
+      await navigator.share({
+        title: 'Continue Flow',
+        url: shareableURL
+      })
+    } else {
+      // Fallback to clipboard
+      await navigator.clipboard.writeText(shareableURL)
+      alert('URL copied to clipboard!')
+    }
+  }
+  
+  return (
+    <button onClick={handleShare}>
+      Share Flow Progress
+    </button>
+  )
+}
+```
+
+### Browser Navigation Integration
+
+```typescript
+import { useNavigate, useLocation } from 'react-router-dom'
+import { useContext } from '@owlmeans/client'
+
+function NavigationAwareFlow() {
+  const context = useContext()
+  const navigate = useNavigate()
+  const location = useLocation()
+  
+  useEffect(() => {
+    // Listen for browser back/forward navigation
+    const handlePopState = async () => {
+      const flowService = context.service('flow')
+      const searchParams = new URLSearchParams(location.search)
+      const flowState = searchParams.get('flow')
+      
+      if (flowState) {
+        await flowService.load(flowState)
+      }
+    }
+    
+    window.addEventListener('popstate', handlePopState)
+    return () => window.removeEventListener('popstate', handlePopState)
+  }, [location])
+  
+  const proceedToStep = async (stepName: string) => {
+    const flowService = context.service('flow')
+    await flowService.proceed({ target: stepName })
+    
+    // Navigation is handled automatically by the web flow service
+  }
+  
+  return (
+    <div>
+      <button onClick={() => proceedToStep('step1')}>Go to Step 1</button>
+      <button onClick={() => proceedToStep('step2')}>Go to Step 2</button>
+      <button onClick={() => navigate(-1)}>Browser Back</button>
+    </div>
+  )
+}
+```
+
+### Custom Query Parameter Configuration
+
+```typescript
+const context = makeClientContext({
+  service: 'custom-app',
+  flowConfig: {
+    defaultFlow: 'checkout',
+    queryParam: 'checkout-state',  // Custom parameter name
+    services: {
+      payment: 'payment-service',
+      shipping: 'shipping-service'
+    }
+  }
+})
+
+appendWebFlowService(context)
+
+// URLs will look like: /checkout?checkout-state=serialized-flow-data
+```
+
+### Flow State Persistence
+
+```typescript
+class WebFlowManager {
+  constructor(private context: ClientContext) {}
+  
+  async saveFlowToURL(): Promise<string> {
+    const flowService = this.context.service('flow')
+    const flow = await flowService.state()
+    
+    if (flow) {
+      const url = new URL(window.location.href)
+      url.searchParams.set('flow', flow.serialize())
+      
+      // Update browser URL without navigation
+      window.history.replaceState({}, '', url.toString())
+      
+      return url.toString()
+    }
+    
+    return window.location.href
+  }
+  
+  async loadFlowFromURL(): Promise<boolean> {
+    const searchParams = new URLSearchParams(window.location.search)
+    const flowState = searchParams.get('flow')
+    
+    if (flowState) {
+      const flowService = this.context.service('flow')
+      await flowService.load(flowState)
+      return true
+    }
+    
+    return false
+  }
+  
+  clearFlowFromURL(): void {
+    const url = new URL(window.location.href)
+    url.searchParams.delete('flow')
+    window.history.replaceState({}, '', url.toString())
+  }
+}
+
+// Usage
+const flowManager = new WebFlowManager(context)
+
+// Save current flow state to URL
+await flowManager.saveFlowToURL()
+
+// Restore flow from URL on page load
+const restored = await flowManager.loadFlowFromURL()
+```
+
+## Integration with React Router
+
+```typescript
+import { BrowserRouter, Routes, Route } from 'react-router-dom'
+import { appendWebFlowService } from '@owlmeans/web-flow'
+
+function App() {
+  const context = makeClientContext(config)
+  appendWebFlowService(context)
+  
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/flow/*" element={<FlowRoutes />} />
+        <Route path="/dashboard" element={<Dashboard />} />
+      </Routes>
+    </BrowserRouter>
+  )
+}
+
+function FlowRoutes() {
+  const context = useContext()
+  const [searchParams] = useSearchParams()
+  
+  // Flow state is automatically managed through URL
+  const flowState = searchParams.get('flow')
+  
+  return (
+    <div>
+      {flowState ? (
+        <ActiveFlowComponent />
+      ) : (
+        <StartFlowComponent />
+      )}
+    </div>
+  )
+}
+```
+
+## Best Practices
+
+1. **URL Management**: Use meaningful query parameter names for flow state
+2. **Browser Integration**: Respect browser navigation patterns
+3. **State Serialization**: Keep flow state minimal for URL storage
+4. **Error Handling**: Handle URL parsing errors gracefully
+5. **SEO Considerations**: Use appropriate meta tags for flow pages
+6. **Performance**: Optimize flow state serialization for large flows
+7. **User Experience**: Provide clear navigation indicators
+
+## Dependencies
+
+This package depends on:
+- `@owlmeans/client-flow` - Base client flow implementation
+- `@owlmeans/client` - React client library
+- `@owlmeans/flow` - Core flow system
+- `react` - React library (peer dependency)
+- `react-router-dom` - React Router DOM (peer dependency)
+
+## Related Packages
+
+- [`@owlmeans/client-flow`](../client-flow) - Base client flow implementation
+- [`@owlmeans/flow`](../flow) - Core flow system
+- [`@owlmeans/server-flow`](../server-flow) - Server-side flow processing
+- [`@owlmeans/client`](../client) - React client library

package/build/consts.d.ts

@@ -0,0 +1,3 @@
+export declare const QUERY_PARAM = "flow";
+export declare const SERVICE_PARAM = "service";
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,WAAW,SAAS,CAAA;AAEjC,eAAO,MAAM,aAAa,YAAY,CAAA"}

package/build/consts.js

@@ -0,0 +1,3 @@
+export const QUERY_PARAM = 'flow';
+export const SERVICE_PARAM = 'service';
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAA;AAEjC,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAA"}

package/build/helper.d.ts

@@ -0,0 +1,3 @@
+import type { FlowClient } from '@owlmeans/client-flow';
+export declare const useFlow: (target?: string | null) => FlowClient | null;
+//# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,uBAAuB,CAAA;AAKpE,eAAO,MAAM,OAAO,YAAY,MAAM,GAAG,IAAI,KAAU,UAAU,GAAG,IAmBnE,CAAA"}

package/build/helper.js

@@ -0,0 +1,24 @@
+import { useContext, useModule, useNavigate, useValue } from '@owlmeans/client';
+import { createFlowClient } from '@owlmeans/client-flow';
+import { DEFAULT_ALIAS as FLOW_ALIAS } from '@owlmeans/client-flow';
+import { useSearchParams } from 'react-router-dom';
+import { QUERY_PARAM, SERVICE_PARAM } from './consts.js';
+export const useFlow = (target = null) => {
+    const context = useContext();
+    const nav = useNavigate();
+    const [query] = useSearchParams();
+    const { params } = useModule();
+    const client = useValue(async () => {
+        if (QUERY_PARAM in params && params[QUERY_PARAM] != null) {
+            const service = context.service(FLOW_ALIAS);
+            await service.ready();
+            return createFlowClient(context, nav).setup(await service.load(params[QUERY_PARAM]));
+        }
+        return createFlowClient(context, nav).boot(query.get(SERVICE_PARAM) ?? target);
+    }, [
+        QUERY_PARAM in params && params[QUERY_PARAM],
+        query.get(QUERY_PARAM), query.get(SERVICE_PARAM) ?? target
+    ]);
+    return client;
+};
+//# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAExD,OAAO,EAAE,aAAa,IAAI,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAExD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,SAAwB,IAAI,EAAqB,EAAE;IACzE,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAC5B,MAAM,GAAG,GAAG,WAAW,EAAE,CAAA;IACzB,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,EAAE,CAAA;IACjC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAAA;IAC9B,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,IAAI,EAAE;QACjC,IAAI,WAAW,IAAI,MAAM,IAAI,MAAM,CAAC,WAAW,CAAC,IAAI,IAAI,EAAE,CAAC;YACzD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAc,UAAU,CAAC,CAAA;YACxD,MAAM,OAAO,CAAC,KAAK,EAAE,CAAA;YAErB,OAAO,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAW,CAAC,CAAC,CAAA;QAChG,CAAC;QACD,OAAO,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,MAAM,CAAC,CAAA;IAChF,CAAC,EAAE;QACD,WAAW,IAAI,MAAM,IAAI,MAAM,CAAC,WAAW,CAAW;QACtD,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,MAAM;KAC3D,CAAC,CAAA;IAEF,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './types.js';
+export * from './service.js';
+export * from './consts.js';
+export * from './helper.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -0,0 +1,4 @@
+export * from './service.js';
+export * from './consts.js';
+export * from './helper.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/service.d.ts

@@ -0,0 +1,5 @@
+import type { ClientContext, ClientConfig } from '@owlmeans/client-context';
+import type { FlowService } from './types.js';
+export declare const makeFlowService: (alias?: string) => FlowService;
+export declare const appendFlowService: <C extends ClientConfig, T extends ClientContext<C>>(ctx: T, alias?: string) => T;
+//# sourceMappingURL=service.d.ts.map

package/build/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAQ7C,eAAO,MAAM,eAAe,WAAW,MAAM,KAAmB,WA4E/D,CAAA;AAED,eAAO,MAAM,iBAAiB,GAC5B,CAAC,SAAS,YAAY,EAAE,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,OAC7C,CAAC,UAAS,MAAM,KAAmB,CAQzC,CAAA"}

package/build/service.js

@@ -0,0 +1,78 @@
+import { DEFAULT_ALIAS, makeBasicFlowService, FLOW_STATE } from '@owlmeans/client-flow';
+import { QUERY_PARAM } from './consts.js';
+import { FlowStepMissconfigured, makeFlowModel, UnknownTransition } from '@owlmeans/flow';
+import { ResilientError } from '@owlmeans/error';
+import { assertContext } from '@owlmeans/context';
+import { appendClientResource } from '@owlmeans/client-resource';
+export const makeFlowService = (alias = DEFAULT_ALIAS) => {
+    const location = `web-flow-service:${alias}`;
+    const service = makeBasicFlowService(alias);
+    // @TODO Use in the client proceed also (unify the code)
+    service.proceed = async (req, dryRun = false) => {
+        const ctx = assertContext(service.ctx, location);
+        const flow = service.flow;
+        if (flow == null) {
+            throw new UnknownTransition('service.proceed');
+        }
+        const step = flow.step();
+        if (step.module == null) {
+            throw new FlowStepMissconfigured(step.step);
+        }
+        const cfg = service.config();
+        const param = cfg.queryParam ?? QUERY_PARAM;
+        const module = ctx.module(step.module);
+        const [url] = await module.call({
+            ...req,
+            params: { ...req?.params, [param]: flow.serialize() },
+            full: true
+        });
+        // const params = new URLSearchParams(req?.query ?? {})
+        // params.set(param, flow.serialize())
+        const redirectUrl = new URL(url);
+        redirectUrl.searchParams.set(param, flow.serialize());
+        if (!dryRun) {
+            document.location.href = redirectUrl.toString();
+        }
+        return redirectUrl.toString();
+    };
+    service.goHome = async (alias, dryRun = false) => {
+        const ctx = assertContext(service.ctx, location);
+        const cfg = await ctx.config;
+        const targetAlias = alias ?? Object.values(cfg.services).find(s => s.default)?.service ?? cfg.service;
+        const target = ctx.serviceRoute(targetAlias);
+        const url = target.home ?? cfg.brand?.home ?? 'https://owlmeans.com';
+        if (!dryRun) {
+            document.location.href = url;
+        }
+        return url;
+    };
+    const init = service.lazyInit;
+    service.lazyInit = async () => {
+        await init();
+        const cfg = service.config();
+        const param = cfg.queryParam ?? QUERY_PARAM;
+        const url = new URL(window.location.href);
+        const state = url.searchParams.get(param);
+        if (state == null) {
+            service.flow = null;
+            service.resolvePair().resolve(false);
+            return;
+        }
+        try {
+            service.flow = await makeFlowModel(state, service.provideFlow);
+            service.resolvePair().resolve(true);
+        }
+        catch (e) {
+            service.flow = null;
+            service.resolvePair().reject(ResilientError.ensure(e));
+        }
+    };
+    return service;
+};
+export const appendFlowService = (ctx, alias = DEFAULT_ALIAS) => {
+    const service = makeFlowService(alias);
+    ctx.registerService(service);
+    appendClientResource(ctx, FLOW_STATE);
+    return ctx;
+};
+//# sourceMappingURL=service.js.map

package/build/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -0,0 +1,5 @@
+import { FlowService as ClientFlowService } from '@owlmeans/client-flow';
+export interface FlowService extends ClientFlowService {
+    goHome: (alias?: string, dryRun?: boolean) => Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAExE,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACpD,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC9D"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@owlmeans/web-flow",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 366 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/client": "^0.1.0",
+    "@owlmeans/client-context": "^0.1.0",
+    "@owlmeans/client-flow": "^0.1.0",
+    "@owlmeans/client-module": "^0.1.0",
+    "@owlmeans/client-resource": "^0.1.0",
+    "@owlmeans/context": "^0.1.0",
+    "@owlmeans/error": "^0.1.0",
+    "@owlmeans/flow": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-router-dom": "*"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.7",
+    "npm-check": "^6.0.1",
+    "typescript": "^5.6.3"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,4 @@
+
+export const QUERY_PARAM = 'flow'
+
+export const SERVICE_PARAM = 'service'

package/src/helper.ts

@@ -0,0 +1,27 @@
+import { useContext, useModule, useNavigate, useValue } from '@owlmeans/client'
+import { createFlowClient } from '@owlmeans/client-flow'
+import type { FlowClient, FlowService } from '@owlmeans/client-flow'
+import { DEFAULT_ALIAS as FLOW_ALIAS } from '@owlmeans/client-flow'
+import { useSearchParams } from 'react-router-dom'
+import { QUERY_PARAM, SERVICE_PARAM } from './consts.js'
+
+export const useFlow = (target: string | null = null): FlowClient | null => {
+  const context = useContext()
+  const nav = useNavigate()
+  const [query] = useSearchParams()
+  const { params } = useModule()
+  const client = useValue(async () => {
+    if (QUERY_PARAM in params && params[QUERY_PARAM] != null) {
+      const service = context.service<FlowService>(FLOW_ALIAS)
+      await service.ready()
+      
+      return createFlowClient(context, nav).setup(await service.load(params[QUERY_PARAM] as string))
+    }
+    return createFlowClient(context, nav).boot(query.get(SERVICE_PARAM) ?? target)
+  }, [
+    QUERY_PARAM in params && params[QUERY_PARAM] as string,
+    query.get(QUERY_PARAM), query.get(SERVICE_PARAM) ?? target
+  ])
+
+  return client
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export type * from './types.js'
+export * from './service.js'
+export * from './consts.js'
+export * from './helper.js'

package/src/service.ts

@@ -0,0 +1,99 @@
+import type { ClientContext, ClientConfig } from '@owlmeans/client-context'
+import { DEFAULT_ALIAS, makeBasicFlowService, FLOW_STATE } from '@owlmeans/client-flow'
+import type { FlowService } from './types.js'
+import { QUERY_PARAM } from './consts.js'
+import { FlowStepMissconfigured, makeFlowModel, UnknownTransition } from '@owlmeans/flow'
+import { ResilientError } from '@owlmeans/error'
+import { assertContext } from '@owlmeans/context'
+import type { ClientModule } from '@owlmeans/client-module'
+import { appendClientResource } from '@owlmeans/client-resource'
+
+export const makeFlowService = (alias: string = DEFAULT_ALIAS): FlowService => {
+  const location = `web-flow-service:${alias}`
+  const service: FlowService = makeBasicFlowService(alias) as FlowService
+
+  // @TODO Use in the client proceed also (unify the code)
+  service.proceed = async (req, dryRun = false) => {
+    const ctx = assertContext(service.ctx, location) as ClientContext
+    const flow = service.flow
+    if (flow == null) {
+      throw new UnknownTransition('service.proceed')
+    }
+    const step = flow.step()
+    if (step.module == null) {
+      throw new FlowStepMissconfigured(step.step)
+    }
+
+    const cfg = service.config()
+    const param = cfg.queryParam ?? QUERY_PARAM
+
+    const module = ctx.module<ClientModule<string>>(step.module)
+    const [url] = await module.call<string>({
+      ...req,
+      params: { ...req?.params, [param]: flow.serialize() },
+      full: true
+    })
+
+    // const params = new URLSearchParams(req?.query ?? {})
+    // params.set(param, flow.serialize())
+
+    const redirectUrl = new URL(url)
+    redirectUrl.searchParams.set(param, flow.serialize())
+
+    if (!dryRun) {
+      document.location.href = redirectUrl.toString()
+    }
+
+    return redirectUrl.toString()
+  }
+
+  service.goHome = async (alias, dryRun = false) => {
+    const ctx = assertContext(service.ctx, location) as ClientContext
+    const cfg = await ctx.config
+    const targetAlias = alias ?? Object.values(cfg.services).find(s => s.default)?.service ?? cfg.service
+    const target = ctx.serviceRoute(targetAlias)
+
+    const url = target.home ?? cfg.brand?.home ?? 'https://owlmeans.com'
+    if (!dryRun) {
+      document.location.href = url
+    }
+
+    return url
+  }
+
+  const init = service.lazyInit
+  service.lazyInit = async () => {
+    await init()
+    const cfg = service.config()
+    const param = cfg.queryParam ?? QUERY_PARAM
+    const url = new URL(window.location.href)
+    const state = url.searchParams.get(param)
+    if (state == null) {
+      service.flow = null
+      service.resolvePair().resolve(false)
+      return
+    }
+
+    try {
+      service.flow = await makeFlowModel(state, service.provideFlow)
+      service.resolvePair().resolve(true)
+    } catch (e) {
+      service.flow = null
+      service.resolvePair().reject(ResilientError.ensure(e as Error))
+    }
+  }
+
+  return service
+}
+
+export const appendFlowService = <
+  C extends ClientConfig, T extends ClientContext<C>
+>(ctx: T, alias: string = DEFAULT_ALIAS): T => {
+  const service = makeFlowService(alias)
+
+  ctx.registerService(service)
+
+  appendClientResource<C, T>(ctx, FLOW_STATE)
+
+  return ctx
+}

package/src/types.ts

@@ -0,0 +1,6 @@
+
+import { FlowService as ClientFlowService } from '@owlmeans/client-flow'
+
+export interface FlowService extends ClientFlowService {
+  goHome: (alias?: string, dryRun?: boolean) => Promise<string>
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": [
+    "../tsconfig.default.json",
+    "../tsconfig.react.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/", /* Specify the root folder within your source files. */
+    "outDir": "./build/", /* Specify an output folder for all emitted files. */
+    "moduleResolution": "Bundler"
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./*.ts"
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/consts.ts","./src/helper.ts","./src/index.ts","./src/service.ts","./src/types.ts"],"version":"5.6.3"}