@owlmeans/web-client 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,617 @@
+# @owlmeans/web-client
+
+A complete React DOM client library for OwlMeans Common applications. This package provides a web-specific implementation that extends `@owlmeans/client` with DOM-specific functionality, including rendering utilities, web database integration, and browser-specific services.
+
+## Overview
+
+The `@owlmeans/web-client` package is the web DOM implementation of the OwlMeans client system. It provides:
+
+- **DOM Rendering**: Direct integration with ReactDOM for web applications
+- **Web Database**: Browser-based database integration with IndexedDB/localStorage
+- **Authentication Integration**: Pre-configured web authentication services
+- **Browser Services**: Web-specific services and utilities
+- **I18n Integration**: Internationalization support for web applications
+- **Router Integration**: Web-specific routing with React Router DOM
+- **Context Management**: Enhanced context with web-specific capabilities
+
+This package is part of the OwlMeans client implementation family:
+- **@owlmeans/client**: Base React client library
+- **@owlmeans/web-client**: Web DOM implementation *(this package)*
+- **@owlmeans/native-client**: React Native implementation
+
+## Installation
+
+```bash
+npm install @owlmeans/web-client react react-dom react-router-dom
+```
+
+## Core Concepts
+
+### Web-First Architecture
+This library is specifically designed for web browsers and provides DOM-specific functionality that isn't available in other environments.
+
+### Enhanced Context
+The web context extends the base client context with web-specific services like database storage, authentication, and browser utilities.
+
+### Integrated Rendering
+Provides seamless integration with ReactDOM including support for both client-side rendering and server-side hydration.
+
+## API Reference
+
+### Factory Functions
+
+#### `makeContext<C, T>(cfg: C): T`
+
+Creates a web-specific application context with all necessary web services pre-configured.
+
+```typescript
+import { makeContext } from '@owlmeans/web-client'
+import { AppType, Layer } from '@owlmeans/context'
+
+const context = makeContext({
+  service: 'my-web-app',
+  type: AppType.Frontend,
+  layer: Layer.Service,
+  ready: false,
+  services: {},
+  brand: { name: 'My Web App' },
+  trusted: []
+})
+```
+
+**Parameters:**
+- `cfg`: AppConfig - Configuration object for the web context
+
+**Returns:** Enhanced AppContext with web-specific capabilities
+
+**Pre-configured Services:**
+- Web authentication service
+- Web database service  
+- Client resource service
+- Primary host extraction
+
+#### `render(node: ReactNode, opts?: RenderOptions): void`
+
+Renders a React application to the DOM with web-specific optimizations.
+
+```typescript
+import { render } from '@owlmeans/web-client'
+import { App } from '@owlmeans/client'
+
+render(
+  <App context={context}>
+    <MyApplication />
+  </App>,
+  {
+    domId: 'root',
+    onReady: true,
+    hydrate: false,
+    debug: true
+  }
+)
+```
+
+**Parameters:**
+- `node`: ReactNode - The React element to render
+- `opts`: RenderOptions (optional) - Rendering configuration
+
+### Core Interfaces
+
+#### `AppContext<C extends AppConfig>`
+
+Web-specific application context that extends ClientContext with authentication capabilities.
+
+```typescript
+interface AppContext<C extends AppConfig = AppConfig> extends ClientContext<C>,
+  AuthServiceAppend {
+  
+  // Inherited from ClientContext:
+  // - Configuration management
+  // - State management
+  // - Modal service
+  // - Debug service
+  // - Module and service registration
+  // - Resource management
+  
+  // Enhanced with authentication:
+  auth(): AuthService
+}
+```
+
+#### `AppConfig`
+
+Configuration interface for web applications (extends ClientConfig).
+
+```typescript
+interface AppConfig extends ClientConfig {
+  // Inherits all ClientConfig properties
+  // Can be extended with web-specific configuration
+}
+```
+
+#### `RenderOptions`
+
+Configuration options for DOM rendering.
+
+```typescript
+interface RenderOptions {
+  domId?: string        // Target DOM element ID (default: 'root')
+  onReady?: boolean     // Wait for DOMContentLoaded (default: true)
+  hydrate?: boolean     // Use hydration for SSR (default: false)
+  debug?: boolean       // Enable debug logging (default: false)
+}
+```
+
+### React Hooks
+
+#### `useContext<C, T>(): T`
+
+Web-specific context hook that provides strongly typed access to the AppContext.
+
+```typescript
+import { useContext } from '@owlmeans/web-client'
+
+function MyWebComponent() {
+  const context = useContext()
+  
+  // Access web-specific services
+  const authService = context.auth()
+  const dbService = context.service('web-db')
+  
+  // Access base client services
+  const stateResource = context.state()
+  const modalService = context.modal()
+  
+  return <div>Web Component</div>
+}
+```
+
+### Web Services
+
+#### Web Database Integration
+
+The package automatically configures web database services:
+
+```typescript
+// Access web database service
+const dbService = context.service('web-db')
+
+// Store data in browser
+await dbService.store('user-preferences', {
+  theme: 'dark',
+  language: 'en'
+})
+
+// Retrieve data from browser
+const preferences = await dbService.retrieve('user-preferences')
+```
+
+#### Authentication Service
+
+Pre-configured web authentication with persistent storage:
+
+```typescript
+// Access authentication service
+const authService = context.auth()
+
+// Authentication persists across browser sessions
+const isAuthenticated = await authService.authenticated()
+```
+
+### Helper Functions
+
+#### `extractPrimaryHost<C, T>(context: T): void`
+
+Extracts and configures the primary host from the current browser location.
+
+**Purpose**: Automatically configures the application's primary host based on the browser's current URL
+
+**Usage**: Called automatically during context creation
+
+### Constants
+
+#### `DEFAULT_ROOT`
+Default DOM element ID for rendering (`'root'`).
+
+### Components and Modules
+
+The package provides web-specific components and modules:
+
+#### I18n Integration
+```typescript
+import { i18nModules } from '@owlmeans/web-client'
+
+// Pre-configured internationalization modules
+context.registerModules(i18nModules)
+```
+
+#### Authentication Components
+```typescript
+import { authComponents } from '@owlmeans/web-client'
+
+// Web-specific authentication components
+// Available through the component system
+```
+
+## Usage Examples
+
+### Complete Web Application Setup
+
+```typescript
+import React from 'react'
+import { makeContext, render } from '@owlmeans/web-client'
+import { App } from '@owlmeans/client'
+import { createBrowserRouter } from 'react-router-dom'
+import { AppType, Layer } from '@owlmeans/context'
+
+// Create web application context
+const context = makeContext({
+  service: 'my-web-app',
+  type: AppType.Frontend,
+  layer: Layer.Service,
+  ready: false,
+  services: {},
+  brand: { 
+    name: 'My Web App',
+    version: '1.0.0'
+  },
+  trusted: ['api.myapp.com']
+})
+
+// Register application modules
+context.registerModules(appModules)
+
+// Configure and initialize
+await context.configure().init()
+
+// Create router provider
+const routerProvider = (routes) => createBrowserRouter(routes)
+
+// Define the application
+function MyWebApp() {
+  return (
+    <App context={context} provide={routerProvider}>
+      <header>My Web Application</header>
+      <main>
+        {/* Application content will be rendered here by the router */}
+      </main>
+    </App>
+  )
+}
+
+// Render to DOM
+render(<MyWebApp />, {
+  domId: 'root',
+  debug: process.env.NODE_ENV === 'development'
+})
+```
+
+### Server-Side Rendering (SSR) with Hydration
+
+```typescript
+import { makeContext, render } from '@owlmeans/web-client'
+import { App } from '@owlmeans/client'
+
+// Create context with SSR data
+const context = makeContext({
+  ...config,
+  ssrData: window.__SSR_DATA__ // Data from server
+})
+
+// Pre-populate context with SSR data
+await context.configure().init()
+
+// Hydrate the server-rendered HTML
+render(
+  <App context={context}>
+    <MyApplication />
+  </App>,
+  {
+    hydrate: true, // Enable hydration
+    onReady: false // Don't wait for DOMContentLoaded
+  }
+)
+```
+
+### Authentication-Enabled Web App
+
+```typescript
+import { makeContext, useContext } from '@owlmeans/web-client'
+import { modules as authModules } from '@owlmeans/client-auth'
+
+// Create context
+const context = makeContext(config)
+
+// Register authentication modules
+context.registerModules(authModules)
+
+// Initialize
+await context.configure().init()
+
+function AuthenticatedApp() {
+  const context = useContext()
+  const [isAuthenticated, setIsAuthenticated] = useState(false)
+  
+  useEffect(() => {
+    const checkAuth = async () => {
+      const authService = context.auth()
+      const token = await authService.authenticated()
+      setIsAuthenticated(token != null)
+    }
+    
+    checkAuth()
+  }, [])
+  
+  if (!isAuthenticated) {
+    return <LoginPage />
+  }
+  
+  return <Dashboard />
+}
+
+// Render with authentication
+render(<AuthenticatedApp />)
+```
+
+### Web Database Usage
+
+```typescript
+import { useContext } from '@owlmeans/web-client'
+import { useEffect, useState } from 'react'
+
+function DataPersistentComponent() {
+  const context = useContext()
+  const [data, setData] = useState(null)
+  
+  useEffect(() => {
+    const loadData = async () => {
+      // Access web database through context
+      const dbService = context.service('web-db')
+      
+      // Load persisted data
+      const savedData = await dbService.retrieve('component-data')
+      setData(savedData || { count: 0 })
+    }
+    
+    loadData()
+  }, [])
+  
+  const saveData = async (newData) => {
+    const dbService = context.service('web-db')
+    await dbService.store('component-data', newData)
+    setData(newData)
+  }
+  
+  const increment = () => {
+    const newData = { count: data.count + 1 }
+    saveData(newData)
+  }
+  
+  return (
+    <div>
+      <p>Count: {data?.count || 0}</p>
+      <button onClick={increment}>Increment</button>
+    </div>
+  )
+}
+```
+
+### Custom Rendering Options
+
+```typescript
+import { render } from '@owlmeans/web-client'
+
+// Render to custom DOM element
+render(<MyApp />, {
+  domId: 'custom-root',
+  debug: true
+})
+
+// Immediate rendering (don't wait for DOMContentLoaded)
+render(<MyApp />, {
+  onReady: false
+})
+
+// Server-side hydration
+render(<MyApp />, {
+  hydrate: true,
+  onReady: false
+})
+```
+
+### Advanced Context Configuration
+
+```typescript
+import { makeContext } from '@owlmeans/web-client'
+
+const context = makeContext({
+  service: 'advanced-app',
+  type: AppType.Frontend,
+  layer: Layer.Service,
+  ready: false,
+  
+  // Web-specific configuration
+  services: {
+    database: { 
+      type: 'indexeddb',
+      name: 'my-app-db'
+    }
+  },
+  
+  // Branding
+  brand: {
+    name: 'Advanced Web App',
+    version: '2.1.0',
+    logo: '/assets/logo.png'
+  },
+  
+  // Trusted hosts for API calls
+  trusted: [
+    'api.myapp.com',
+    'cdn.myapp.com'
+  ],
+  
+  // Debug configuration
+  debug: {
+    all: process.env.NODE_ENV === 'development',
+    routing: true,
+    auth: true
+  }
+})
+
+// Additional service registration
+context.registerService(customWebService)
+
+// Module registration with web-specific modules
+context.registerModules([
+  ...appModules,
+  ...webSpecificModules
+])
+```
+
+### Integration with Internationalization
+
+```typescript
+import { makeContext } from '@owlmeans/web-client'
+import { addI18nApp } from '@owlmeans/i18n'
+
+// Add web-specific translations
+addI18nApp('en', 'web-common', {
+  'button.close': 'Close',
+  'message.loading': 'Loading...',
+  'error.network': 'Network error occurred'
+})
+
+const context = makeContext(config)
+
+// Access i18n through context
+function I18nComponent() {
+  const context = useContext()
+  const i18nService = context.service('i18n')
+  
+  return (
+    <div>
+      <button>{i18nService.t('button.close')}</button>
+    </div>
+  )
+}
+```
+
+## Browser Compatibility
+
+The package is designed for modern web browsers with support for:
+
+- **ES2020+**: Modern JavaScript features
+- **IndexedDB**: For local database storage
+- **LocalStorage**: For simple key-value storage
+- **DOM API**: Standard DOM manipulation
+- **Fetch API**: For HTTP requests
+- **WebCrypto**: For cryptographic operations (if used)
+
+## Performance Optimizations
+
+1. **Lazy Loading**: Components and services are loaded on demand
+2. **Efficient Rendering**: Optimized ReactDOM integration
+3. **Database Caching**: Intelligent caching of web database operations
+4. **Bundle Splitting**: Designed for code splitting compatibility
+5. **SSR Ready**: Full server-side rendering support
+
+## Error Handling
+
+Web-specific error handling and reporting:
+
+```typescript
+import { OwlMeansError } from '@owlmeans/error'
+
+// Web-specific error boundary
+class WebErrorBoundary extends React.Component {
+  componentDidCatch(error, errorInfo) {
+    const context = this.props.context
+    const debugService = context.debug()
+    
+    // Log web-specific error details
+    debugService.error('web-error', 'Browser error', {
+      error: error.message,
+      stack: error.stack,
+      userAgent: navigator.userAgent,
+      url: window.location.href
+    })
+  }
+}
+```
+
+## Security Considerations
+
+1. **Trusted Hosts**: Configure trusted hosts to prevent CSRF attacks
+2. **Authentication Storage**: Secure token storage in browser
+3. **XSS Protection**: Built-in protection against cross-site scripting
+4. **Content Security Policy**: Compatible with CSP headers
+5. **HTTPS Only**: Designed for secure HTTPS environments
+
+## Integration with Other Packages
+
+### Client Ecosystem Integration
+```typescript
+// Authentication
+import { makeAuthService } from '@owlmeans/client-auth'
+
+// Resources
+import { makeResourceService } from '@owlmeans/client-resource'
+
+// Internationalization
+import { makeI18nService } from '@owlmeans/client-i18n'
+
+// Database
+import { WebDbService } from '@owlmeans/web-db'
+```
+
+### Build Tool Integration
+```typescript
+// Webpack configuration
+module.exports = {
+  resolve: {
+    alias: {
+      '@owlmeans/web-client': path.resolve(__dirname, 'node_modules/@owlmeans/web-client')
+    }
+  }
+}
+
+// Vite configuration
+export default {
+  resolve: {
+    alias: {
+      '@owlmeans/web-client': path.resolve(__dirname, 'node_modules/@owlmeans/web-client')
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Single Context**: Use one web context per application
+2. **Proper Hydration**: Use hydration mode for SSR applications
+3. **Error Boundaries**: Implement web-specific error boundaries
+4. **Performance Monitoring**: Monitor web-specific performance metrics
+5. **Responsive Design**: Ensure proper responsive behavior
+6. **Accessibility**: Follow web accessibility guidelines
+7. **SEO Optimization**: Use SSR for better search engine optimization
+
+## Dependencies
+
+This package depends on:
+- `@owlmeans/client` - Base React client library
+- `@owlmeans/client-context` - Client context management
+- `@owlmeans/client-auth` - Client authentication
+- `@owlmeans/web-db` - Web database integration
+- `@owlmeans/client-i18n` - Client internationalization
+- `react` - React library (peer dependency)
+- `react-dom` - ReactDOM library (peer dependency)
+- `react-router-dom` - React Router DOM (peer dependency)
+
+## Related Packages
+
+- [`@owlmeans/client`](../client) - Base React client library
+- [`@owlmeans/native-client`](../native-client) - React Native implementation
+- [`@owlmeans/web-db`](../web-db) - Web database implementation
+- [`@owlmeans/client-auth`](../client-auth) - Client authentication
+- [`@owlmeans/client-i18n`](../client-i18n) - Client internationalization

package/build/components/dispatcher/component.d.ts

@@ -0,0 +1,2 @@
+export declare const Dispatcher: import("@owlmeans/client").RoutedComponent<import("@owlmeans/client-auth").DispatcherProps>;
+//# sourceMappingURL=component.d.ts.map

package/build/components/dispatcher/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../../src/components/dispatcher/component.tsx"],"names":[],"mappings":"AAOA,eAAO,MAAM,UAAU,6FAmCrB,CAAA"}

package/build/components/dispatcher/component.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { DispatcherHOC } from '@owlmeans/client-auth';
+import { useEffect } from 'react';
+import { useSearchParams } from 'react-router-dom';
+import { useI18nLib } from '@owlmeans/client-i18n';
+import { AUTH_QUERY } from '@owlmeans/auth';
+import { useContext } from '../../context.js';
+export const Dispatcher = DispatcherHOC(({ provideToken }) => {
+    const [query] = useSearchParams();
+    const context = useContext();
+    const t = useI18nLib('auth', 'dispatcher');
+    useEffect(() => {
+        const token = query.get(AUTH_QUERY);
+        if (token != null) {
+            const params = {};
+            query.forEach((value, key) => {
+                if (key !== AUTH_QUERY) {
+                    params[key] = value;
+                }
+            });
+            provideToken({ token }, params);
+        }
+        else {
+            context.auth().authenticated().then(authzToken => {
+                if (authzToken == null) {
+                    provideToken({ token: '' }, undefined);
+                }
+            });
+        }
+    }, []);
+    return query.has(AUTH_QUERY) ? _jsx("div", { style: {
+            width: '100%', // Makes the div occupy the full width
+            display: 'flex', // Enables flexbox layout
+            justifyContent: 'center', // Centers content horizontally
+            alignItems: 'center', // Centers content vertically (if needed)
+            textAlign: 'center', // Centers text within the div
+            paddingTop: '1rem', // Adds some vertical padding
+            paddingBottom: '1rem', // Adds some vertical padding
+        }, children: t('loading') }) : undefined;
+});
+//# sourceMappingURL=component.js.map

package/build/components/dispatcher/component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.js","sourceRoot":"","sources":["../../../src/components/dispatcher/component.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,MAAM,CAAC,MAAM,UAAU,GAAG,aAAa,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE;IAC3D,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,EAAE,CAAA;IACjC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAA;IAE5B,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IAE1C,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;QACnC,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;YAClB,MAAM,MAAM,GAA2B,EAAE,CAAA;YACzC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC3B,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;oBACvB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;gBACrB,CAAC;YACH,CAAC,CAAC,CAAA;YAEF,YAAY,CAAC,EAAE,KAAK,EAAE,EAAE,MAAM,CAAC,CAAA;QACjC,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,EAAE,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE;gBAC/C,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;oBACvB,YAAY,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,SAAS,CAAC,CAAA;gBACxC,CAAC;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,cAAK,KAAK,EAAE;YACzC,KAAK,EAAE,MAAM,EAAE,sCAAsC;YACrD,OAAO,EAAE,MAAM,EAAE,yBAAyB;YAC1C,cAAc,EAAE,QAAQ,EAAE,+BAA+B;YACzD,UAAU,EAAE,QAAQ,EAAE,yCAAyC;YAC/D,SAAS,EAAE,QAAQ,EAAE,8BAA8B;YACnD,UAAU,EAAE,MAAM,EAAE,6BAA6B;YACjD,aAAa,EAAE,MAAM,EAAE,6BAA6B;SACrD,YAAG,CAAC,CAAC,SAAS,CAAC,GAAO,CAAC,CAAC,CAAC,SAAS,CAAA;AACrC,CAAC,CAAC,CAAA"}

package/build/components/dispatcher/index.d.ts

@@ -0,0 +1,2 @@
+export * from './component.js';
+//# sourceMappingURL=index.d.ts.map

package/build/components/dispatcher/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/dispatcher/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAA"}

package/build/components/dispatcher/index.js

@@ -0,0 +1,2 @@
+export * from './component.js';
+//# sourceMappingURL=index.js.map

package/build/components/dispatcher/index.js.map

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