@object-ui/providers 3.3.1 → 3.3.3

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @object-ui/providers — Changelog
 
+## 3.3.3
+
+### Patch Changes
+
+- a2d7023: End-user feature batch — forms, designer history, import/export, and PWA offline sync.
+
+  **Forms (`@object-ui/fields`, `@object-ui/providers`)**
+  - `FileField`: native `<input capture="environment">` camera capture for mobile devices, plus a uploading-progress indicator driven by `UploadProvider`.
+  - `ImageField`: per-image inline crop/rotate via the lazy-loaded `ImageCropperDialog` (canvas-based, zero new deps).
+  - New `UploadProvider` in `@object-ui/providers` with pluggable adapters for S3 and Azure Blob (plus the default object-URL adapter for local previews). XHR-based with progress, abort, and retry.
+  - `LookupField`: `lookup.dependsOn: string | string[]` to chain dependent lookups (e.g. State depends on Country); the trigger is gated until parent values are present and the OData `$filter` is built automatically.
+
+  **Container-aware widget widths (`@object-ui/components`)**
+  - New `useResizeObserver(ref)` hook exposing `{ width, height }` of any element. SSR-safe; reads the initial size via `getBoundingClientRect`.
+  - `plugin-gantt` and `plugin-kanban` now react to their container size instead of `window.innerWidth`, so they behave correctly inside split panels and dashboards.
+
+  **Designer history (`@object-ui/plugin-designer`)**
+  - `useUndoRedo` (and therefore `useDesignerHistory`) gains `persistKey` + `storage` options to round-trip the undo/redo stack through `sessionStorage`, plus a `clearPersisted()` cleanup helper. Drafts now survive accidental tab refreshes.
+  - New `<HistoryPanel>` component renders the timeline visually with one-click jump-to-checkpoint via the new `jumpTo(index)` API.
+
+  **Import wizard (`@object-ui/plugin-grid`)**
+  - Saved column-mapping templates: name, save, re-apply, and delete via a new template bar in the mapping step. Persisted under `objectui:import-templates:${objectName}` (override via `templateStorageKey` / `templateStorage`).
+  - Inline validation correction: cells with errors in the preview step are now editable; corrections feed straight into the import without requiring a re-upload, with green-bar status indicators for fixed rows.
+
+  **PWA offline sync (`@object-ui/mobile`)**
+  - New `MemoryOfflineQueue` / `IndexedDbOfflineQueue` (`createOfflineQueue()` picks the best backend) backed by IndexedDB.
+  - `createOfflineDataSource(inner, { queue })` wraps any DataSource so mutations issued while offline (or that fail with a network-style error) are queued and replayed in order on reconnect. Includes `replay()`, `drop()`, `clear()`, `pending()`, an `onChange` notifier, and an opt-in `resolveConflict` hook for stale-write conflicts.
+  - New `useOfflineSync(source)` hook exposes `{ isOnline, pending, isReplaying, replay, drop, clear }` and auto-replays on the browser's `online` event.
+  - `getServiceWorkerSource(opts)` emits a customisable Service Worker that pre-caches the app shell, applies network-first to API requests, and broadcasts `REPLAY_QUEUE` to clients on Background Sync. `requestBackgroundSync(tag)` registers a one-shot sync from the page.
+
+- Updated dependencies [f1ca238]
+- Updated dependencies [de881ef]
+  - @object-ui/types@3.4.0
+
+## 3.3.2
+
+### Patch Changes
+
+- @object-ui/types@3.3.2
+
 ## 3.3.1
 
 ### Patch Changes

package/dist/UploadProvider.d.ts

@@ -0,0 +1,115 @@
+/**
+ * UploadProvider — pluggable file upload context for ObjectUI.
+ *
+ * Why: `FileField` and `ImageField` historically used `URL.createObjectURL(file)`
+ * which only works for the lifetime of the browser tab and never persists the
+ * file anywhere. Production deployments need to push the bytes to S3, Azure
+ * Blob, or another object store and replace the temporary blob URL with a
+ * canonical one.
+ *
+ * Design:
+ * - `UploadProvider` exposes an `upload(file, opts)` function via context.
+ * - Apps inject an adapter (`createS3Adapter`, `createAzureBlobAdapter`, or any
+ *   custom one implementing `UploadAdapter`).
+ * - The default adapter (`createObjectUrlAdapter`) preserves the legacy
+ *   "blob: URL" behaviour so the field widgets keep working when no provider
+ *   is mounted.
+ * - Upload progress and resumable retries are first-class concerns: each
+ *   adapter implementation can chunk + resume; the public API surfaces
+ *   `onProgress` and an `abortSignal`.
+ */
+import React, { type ReactNode } from 'react';
+export interface UploadResult {
+    /** Canonical, shareable URL (e.g. https://my-bucket.s3.amazonaws.com/avatars/abc.png). */
+    url: string;
+    /** Stored object name / key. */
+    name: string;
+    size: number;
+    mimeType: string;
+    /** Adapter-specific metadata (etag, version, etc.). */
+    meta?: Record<string, unknown>;
+}
+export interface UploadOptions {
+    /** Logical folder / key prefix (e.g. "avatars/"). */
+    path?: string;
+    /** Progress callback in 0–1. */
+    onProgress?: (ratio: number) => void;
+    /** External abort signal — cancels the upload (and any retry attempts). */
+    signal?: AbortSignal;
+    /** Number of retry attempts on network failure. @default 3 */
+    maxRetries?: number;
+    /** Initial backoff in ms; exponential. @default 500 */
+    retryDelayMs?: number;
+}
+export interface UploadAdapter {
+    readonly name: string;
+    upload(file: File | Blob, opts?: UploadOptions): Promise<UploadResult>;
+}
+interface UploadContextValue {
+    upload: (file: File | Blob, opts?: UploadOptions) => Promise<UploadResult>;
+    adapter: UploadAdapter;
+}
+/**
+ * Default adapter — wraps the file in an object URL. Identical to the legacy
+ * field-widget behaviour; safe fallback when the app hasn't configured a real
+ * upload destination yet.
+ */
+export declare function createObjectUrlAdapter(): UploadAdapter;
+export interface S3AdapterOptions {
+    /**
+     * URL of an endpoint that returns `{ uploadUrl, publicUrl, headers? }`
+     * for a given `{ name, type, size }`. Implementations typically presign an
+     * S3 PUT URL server-side.
+     */
+    getPresignedUrl: (input: {
+        name: string;
+        type: string;
+        size: number;
+        path?: string;
+    }) => Promise<{
+        uploadUrl: string;
+        publicUrl: string;
+        headers?: Record<string, string>;
+    }>;
+    /** Override fetch (useful for tests and ServiceWorker offline queues). */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * S3-style adapter — relies on the app to provide a presign endpoint so that
+ * AWS credentials never leak to the browser. Works with any S3-compatible
+ * object store (AWS S3, Cloudflare R2, MinIO, …).
+ */
+export declare function createS3Adapter(opts: S3AdapterOptions): UploadAdapter;
+export interface AzureBlobAdapterOptions {
+    /**
+     * URL of an endpoint that returns `{ uploadUrl, publicUrl }` — typically a
+     * short-lived SAS URL minted server-side.
+     */
+    getSasUrl: (input: {
+        name: string;
+        type: string;
+        size: number;
+        path?: string;
+    }) => Promise<{
+        uploadUrl: string;
+        publicUrl: string;
+    }>;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Azure Blob Storage adapter using SAS tokens. Single PUT — for files larger
+ * than ~256 MiB, callers should issue chunked SAS URLs (block list + commit)
+ * via their backend.
+ */
+export declare function createAzureBlobAdapter(opts: AzureBlobAdapterOptions): UploadAdapter;
+export interface UploadProviderProps {
+    adapter?: UploadAdapter;
+    children: ReactNode;
+}
+export declare const UploadProvider: React.FC<UploadProviderProps>;
+/**
+ * Hook returning the configured upload function. Falls back to a fresh
+ * object-URL adapter so widgets never crash when used outside a provider.
+ */
+export declare function useUpload(): UploadContextValue;
+export {};

package/dist/UploadProvider.js

@@ -0,0 +1,211 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * UploadProvider — pluggable file upload context for ObjectUI.
+ *
+ * Why: `FileField` and `ImageField` historically used `URL.createObjectURL(file)`
+ * which only works for the lifetime of the browser tab and never persists the
+ * file anywhere. Production deployments need to push the bytes to S3, Azure
+ * Blob, or another object store and replace the temporary blob URL with a
+ * canonical one.
+ *
+ * Design:
+ * - `UploadProvider` exposes an `upload(file, opts)` function via context.
+ * - Apps inject an adapter (`createS3Adapter`, `createAzureBlobAdapter`, or any
+ *   custom one implementing `UploadAdapter`).
+ * - The default adapter (`createObjectUrlAdapter`) preserves the legacy
+ *   "blob: URL" behaviour so the field widgets keep working when no provider
+ *   is mounted.
+ * - Upload progress and resumable retries are first-class concerns: each
+ *   adapter implementation can chunk + resume; the public API surfaces
+ *   `onProgress` and an `abortSignal`.
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, } from 'react';
+const UploadContext = createContext(null);
+/**
+ * Default adapter — wraps the file in an object URL. Identical to the legacy
+ * field-widget behaviour; safe fallback when the app hasn't configured a real
+ * upload destination yet.
+ */
+export function createObjectUrlAdapter() {
+    return {
+        name: 'object-url',
+        async upload(file) {
+            const f = file;
+            const name = ('name' in f && f.name) || 'upload';
+            return {
+                url: URL.createObjectURL(file),
+                name,
+                size: file.size,
+                mimeType: file.type || 'application/octet-stream',
+            };
+        },
+    };
+}
+/**
+ * S3-style adapter — relies on the app to provide a presign endpoint so that
+ * AWS credentials never leak to the browser. Works with any S3-compatible
+ * object store (AWS S3, Cloudflare R2, MinIO, …).
+ */
+export function createS3Adapter(opts) {
+    const fetchFn = opts.fetchImpl ?? fetch;
+    return {
+        name: 's3',
+        async upload(file, options = {}) {
+            const f = file;
+            const name = ('name' in f && f.name) || 'upload';
+            const presigned = await opts.getPresignedUrl({
+                name,
+                type: file.type || 'application/octet-stream',
+                size: file.size,
+                path: options.path,
+            });
+            await uploadWithProgress(fetchFn, presigned.uploadUrl, file, {
+                method: 'PUT',
+                headers: presigned.headers,
+                ...options,
+            });
+            return {
+                url: presigned.publicUrl,
+                name,
+                size: file.size,
+                mimeType: file.type || 'application/octet-stream',
+            };
+        },
+    };
+}
+/**
+ * Azure Blob Storage adapter using SAS tokens. Single PUT — for files larger
+ * than ~256 MiB, callers should issue chunked SAS URLs (block list + commit)
+ * via their backend.
+ */
+export function createAzureBlobAdapter(opts) {
+    const fetchFn = opts.fetchImpl ?? fetch;
+    return {
+        name: 'azure-blob',
+        async upload(file, options = {}) {
+            const f = file;
+            const name = ('name' in f && f.name) || 'upload';
+            const sas = await opts.getSasUrl({
+                name,
+                type: file.type || 'application/octet-stream',
+                size: file.size,
+                path: options.path,
+            });
+            await uploadWithProgress(fetchFn, sas.uploadUrl, file, {
+                method: 'PUT',
+                headers: {
+                    'x-ms-blob-type': 'BlockBlob',
+                    'Content-Type': file.type || 'application/octet-stream',
+                },
+                ...options,
+            });
+            return {
+                url: sas.publicUrl,
+                name,
+                size: file.size,
+                mimeType: file.type || 'application/octet-stream',
+            };
+        },
+    };
+}
+/**
+ * Internal helper — performs a single PUT/POST with progress reporting,
+ * exponential-backoff retry, and abort propagation.
+ */
+async function uploadWithProgress(fetchFn, url, body, options) {
+    const maxRetries = options.maxRetries ?? 3;
+    const baseDelay = options.retryDelayMs ?? 500;
+    let attempt = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        if (options.signal?.aborted)
+            throw new DOMException('aborted', 'AbortError');
+        try {
+            // Fetch's standard progress reporting is limited; use XHR when we need
+            // per-byte progress. Falls back to fetch for environments without XHR
+            // (e.g. Cloudflare Workers used by Service Workers).
+            if (typeof XMLHttpRequest !== 'undefined' && options.onProgress) {
+                await xhrUpload(url, body, options);
+            }
+            else {
+                const res = await fetchFn(url, {
+                    method: options.method,
+                    body,
+                    headers: options.headers,
+                    signal: options.signal,
+                });
+                if (!res.ok)
+                    throw new Error(`Upload failed with status ${res.status}`);
+                options.onProgress?.(1);
+            }
+            return;
+        }
+        catch (err) {
+            if (err?.name === 'AbortError')
+                throw err;
+            if (attempt >= maxRetries)
+                throw err;
+            const delay = baseDelay * Math.pow(2, attempt);
+            attempt++;
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+}
+function xhrUpload(url, body, options) {
+    return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open(options.method, url);
+        if (options.headers) {
+            for (const [k, v] of Object.entries(options.headers))
+                xhr.setRequestHeader(k, v);
+        }
+        xhr.upload.onprogress = (e) => {
+            if (e.lengthComputable && options.onProgress)
+                options.onProgress(e.loaded / e.total);
+        };
+        xhr.onload = () => {
+            if (xhr.status >= 200 && xhr.status < 300) {
+                options.onProgress?.(1);
+                resolve();
+            }
+            else {
+                reject(new Error(`Upload failed with status ${xhr.status}`));
+            }
+        };
+        xhr.onerror = () => reject(new Error('Network error during upload'));
+        xhr.onabort = () => reject(new DOMException('aborted', 'AbortError'));
+        if (options.signal) {
+            const abortHandler = () => xhr.abort();
+            if (options.signal.aborted) {
+                xhr.abort();
+            }
+            else {
+                options.signal.addEventListener('abort', abortHandler, { once: true });
+            }
+        }
+        xhr.send(body);
+    });
+}
+export const UploadProvider = ({ adapter, children }) => {
+    const adapterRef = useRef(adapter ?? createObjectUrlAdapter());
+    useEffect(() => {
+        if (adapter)
+            adapterRef.current = adapter;
+    }, [adapter]);
+    const upload = useCallback((file, opts) => adapterRef.current.upload(file, opts), []);
+    const value = useMemo(() => ({ upload, adapter: adapterRef.current }), [upload]);
+    return _jsx(UploadContext.Provider, { value: value, children: children });
+};
+/**
+ * Hook returning the configured upload function. Falls back to a fresh
+ * object-URL adapter so widgets never crash when used outside a provider.
+ */
+export function useUpload() {
+    const ctx = useContext(UploadContext);
+    // Always call useMemo to honour the rules of hooks; cheap when ctx is set.
+    const fallback = useMemo(() => {
+        const a = createObjectUrlAdapter();
+        return { upload: (f, o) => a.upload(f, o), adapter: a };
+    }, []);
+    return ctx ?? fallback;
+}

package/dist/index.d.ts

@@ -6,4 +6,6 @@
 export { DataSourceProvider, useDataSource } from './DataSourceProvider';
 export { MetadataProvider, useMetadata } from './MetadataProvider';
 export { ThemeProvider, useTheme } from './ThemeProvider';
+export { UploadProvider, useUpload, createObjectUrlAdapter, createS3Adapter, createAzureBlobAdapter, } from './UploadProvider';
 export type { DataSourceProviderProps, MetadataProviderProps, ThemeProviderProps, Theme, } from './types';
+export type { UploadAdapter, UploadOptions, UploadResult, UploadProviderProps, S3AdapterOptions, AzureBlobAdapterOptions, } from './UploadProvider';

package/dist/index.js

@@ -6,3 +6,4 @@
 export { DataSourceProvider, useDataSource } from './DataSourceProvider';
 export { MetadataProvider, useMetadata } from './MetadataProvider';
 export { ThemeProvider, useTheme } from './ThemeProvider';
+export { UploadProvider, useUpload, createObjectUrlAdapter, createS3Adapter, createAzureBlobAdapter, } from './UploadProvider';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/providers",
-  "version": "3.3.1",
+  "version": "3.3.3",
   "type": "module",
   "license": "MIT",
   "description": "Reusable context providers for ObjectUI applications",
@@ -24,7 +24,7 @@
     }
   },
   "dependencies": {
-    "@object-ui/types": "3.3.1"
+    "@object-ui/types": "3.4.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",