@object-ui/mobile 3.3.2 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @object-ui/mobile
 
+## 3.4.0
+
+### 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

package/dist/createOfflineDataSource.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * `createOfflineDataSource` — wraps any DataSource so that mutations made
+ * while the network is offline (or while the inner source rejects with a
+ * network-style error) are persisted to an offline queue and replayed
+ * automatically when connectivity returns.
+ *
+ * Reads (`find` / `findOne`) are pass-through; the optional `cache` hook
+ * lets callers opt into local caching but is not built in here.
+ */
+import { type OfflineQueueBackend, type OfflineOperation } from './offlineQueue';
+/** Minimal DataSource shape we care about. */
+export interface QueueableDataSource {
+    find?: (object: string, query?: any) => Promise<any>;
+    findOne?: (object: string, id: string | number, query?: any) => Promise<any>;
+    create?: (object: string, payload: any) => Promise<any>;
+    update?: (object: string, id: string | number, payload: any) => Promise<any>;
+    delete?: (object: string, id: string | number) => Promise<any>;
+    [k: string]: any;
+}
+export interface OfflineDataSourceOptions {
+    queue: OfflineQueueBackend;
+    /** Custom predicate to detect network failure. Defaults to instanceof TypeError + 5xx. */
+    isNetworkError?: (err: unknown) => boolean;
+    /** Override online detection. Defaults to `navigator.onLine`. */
+    isOnline?: () => boolean;
+    /** Called whenever queue contents change (enqueue / replay / drop). */
+    onChange?: (ops: OfflineOperation[]) => void;
+    /**
+     * Optional conflict resolver. Returns `'retry'` to leave the op in place,
+     * `'drop'` to discard, or a fresh payload to retry with overrides.
+     */
+    resolveConflict?: (op: OfflineOperation, error: unknown) => Promise<'retry' | 'drop' | {
+        payload: any;
+    }>;
+}
+/** A DataSource wrapper that queues mutations while offline. */
+export interface OfflineDataSource extends QueueableDataSource {
+    /** Number of pending operations (sync, may lag a tick — call `pendingCount()` for fresh). */
+    pendingCount(): Promise<number>;
+    /** Replay all pending ops in order. Returns counts. */
+    replay(): Promise<{
+        succeeded: number;
+        failed: number;
+        remaining: number;
+    }>;
+    /** Drop a specific queued op (e.g. from a UI). */
+    drop(opId: string): Promise<void>;
+    /** Drop all queued ops (e.g. "discard local changes"). */
+    clear(): Promise<void>;
+    /** Inspect all queued ops. */
+    pending(): Promise<OfflineOperation[]>;
+}
+/**
+ * Wrap an inner DataSource. Mutations that fail with a network-style error
+ * — or are issued while offline — are stored in the queue and replayed on
+ * reconnect.
+ */
+export declare function createOfflineDataSource(inner: QueueableDataSource, options: OfflineDataSourceOptions): OfflineDataSource;
+//# sourceMappingURL=createOfflineDataSource.d.ts.map

package/dist/createOfflineDataSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createOfflineDataSource.d.ts","sourceRoot":"","sources":["../src/createOfflineDataSource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,gBAAgB,EAAgB,MAAM,gBAAgB,CAAC;AAE/F,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACrD,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7E,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7E,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/D,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,mBAAmB,CAAC;IAC3B,0FAA0F;IAC1F,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IAC3C,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,EAAE,KAAK,IAAI,CAAC;IAC7C;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,GAAG,MAAM,GAAG;QAAE,OAAO,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;CAC1G;AAiBD,gEAAgE;AAChE,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,6FAA6F;IAC7F,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,uDAAuD;IACvD,MAAM,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5E,kDAAkD;IAClD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,0DAA0D;IAC1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,8BAA8B;IAC9B,OAAO,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;CACxC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,CA6GnB"}

package/dist/createOfflineDataSource.js

@@ -0,0 +1,146 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * `createOfflineDataSource` — wraps any DataSource so that mutations made
+ * while the network is offline (or while the inner source rejects with a
+ * network-style error) are persisted to an offline queue and replayed
+ * automatically when connectivity returns.
+ *
+ * Reads (`find` / `findOne`) are pass-through; the optional `cache` hook
+ * lets callers opt into local caching but is not built in here.
+ */
+import { generateOpId } from './offlineQueue';
+const defaultIsNetworkError = (err) => {
+    if (!err)
+        return false;
+    if (err instanceof TypeError)
+        return true;
+    const e = err;
+    if (e.code === 'ENOTFOUND' || e.code === 'ECONNREFUSED' || e.code === 'NETWORK_ERROR')
+        return true;
+    if (typeof e.status === 'number' && e.status >= 500)
+        return true;
+    if (typeof e.message === 'string' && /network|fetch|offline/i.test(e.message))
+        return true;
+    return false;
+};
+const defaultIsOnline = () => {
+    if (typeof navigator === 'undefined')
+        return true;
+    return navigator.onLine !== false;
+};
+/**
+ * Wrap an inner DataSource. Mutations that fail with a network-style error
+ * — or are issued while offline — are stored in the queue and replayed on
+ * reconnect.
+ */
+export function createOfflineDataSource(inner, options) {
+    const { queue, onChange } = options;
+    const isNetErr = options.isNetworkError ?? defaultIsNetworkError;
+    const isOnline = options.isOnline ?? defaultIsOnline;
+    const notify = async () => {
+        if (!onChange)
+            return;
+        try {
+            onChange(await queue.list());
+        }
+        catch { /* ignore */ }
+    };
+    const enqueue = async (op) => {
+        const full = {
+            id: generateOpId(),
+            enqueuedAt: Date.now(),
+            attempts: 0,
+            ...op,
+        };
+        await queue.enqueue(full);
+        await notify();
+        return full;
+    };
+    // Optimistic helper: try the inner mutation, queue on network failure.
+    const guarded = async (op, runner) => {
+        if (!isOnline()) {
+            const queued = await enqueue(op);
+            return { queued: true, op: queued };
+        }
+        try {
+            return await runner();
+        }
+        catch (err) {
+            if (isNetErr(err)) {
+                const queued = await enqueue(op);
+                return { queued: true, op: queued };
+            }
+            throw err;
+        }
+    };
+    const wrapped = {
+        ...inner,
+        find: inner.find?.bind(inner),
+        findOne: inner.findOne?.bind(inner),
+        create: inner.create
+            ? (object, payload) => guarded({ op: 'create', object, payload }, () => inner.create(object, payload))
+            : undefined,
+        update: inner.update
+            ? (object, id, payload) => guarded({ op: 'update', object, recordId: id, payload }, () => inner.update(object, id, payload))
+            : undefined,
+        delete: inner.delete
+            ? (object, id) => guarded({ op: 'delete', object, recordId: id }, () => inner.delete(object, id))
+            : undefined,
+        async pendingCount() { return (await queue.list()).length; },
+        async pending() { return queue.list(); },
+        async drop(opId) { await queue.remove(opId); await notify(); },
+        async clear() { await queue.clear(); await notify(); },
+        async replay() {
+            let succeeded = 0;
+            let failed = 0;
+            const ops = await queue.list();
+            for (const op of ops) {
+                try {
+                    if (op.op === 'create' && inner.create)
+                        await inner.create(op.object, op.payload);
+                    else if (op.op === 'update' && inner.update)
+                        await inner.update(op.object, op.recordId, op.payload);
+                    else if (op.op === 'delete' && inner.delete)
+                        await inner.delete(op.object, op.recordId);
+                    else
+                        throw new Error(`Unsupported op: ${op.op}`);
+                    await queue.remove(op.id);
+                    succeeded++;
+                }
+                catch (err) {
+                    // Non-network failures may be conflicts: ask the resolver.
+                    if (!isNetErr(err) && options.resolveConflict) {
+                        const decision = await options.resolveConflict(op, err);
+                        if (decision === 'drop') {
+                            await queue.remove(op.id);
+                            succeeded++;
+                            continue;
+                        }
+                        if (typeof decision === 'object' && 'payload' in decision) {
+                            const next = { ...op, payload: decision.payload, attempts: op.attempts + 1 };
+                            await queue.update(next);
+                            continue;
+                        }
+                        // 'retry' falls through to bumping attempts below.
+                    }
+                    const next = {
+                        ...op,
+                        attempts: op.attempts + 1,
+                        lastError: err instanceof Error ? err.message : String(err),
+                    };
+                    await queue.update(next);
+                    failed++;
+                    // For network errors stop processing — we'll likely fail the rest too.
+                    if (isNetErr(err))
+                        break;
+                }
+            }
+            const remaining = (await queue.list()).length;
+            await notify();
+            return { succeeded, failed, remaining };
+        },
+    };
+    return wrapped;
+}

package/dist/index.d.ts

@@ -28,6 +28,10 @@ export { MobileProvider, type MobileProviderProps } from './MobileProvider';
 export { ResponsiveContainer, type ResponsiveContainerProps } from './ResponsiveContainer';
 export { generatePWAManifest } from './pwa';
 export { registerServiceWorker, type ServiceWorkerConfig } from './serviceWorker';
+export { createOfflineQueue, IndexedDbOfflineQueue, MemoryOfflineQueue, generateOpId, type OfflineOperation, type OfflineQueueBackend, } from './offlineQueue';
+export { createOfflineDataSource, type OfflineDataSource, type OfflineDataSourceOptions, type QueueableDataSource, } from './createOfflineDataSource';
+export { useOfflineSync, type OfflineSyncState } from './useOfflineSync';
+export { getServiceWorkerSource, requestBackgroundSync, type ServiceWorkerSourceOptions, } from './serviceWorkerSource';
 export { BREAKPOINTS, resolveResponsiveValue } from './breakpoints';
 export type { BreakpointName, ResponsiveValue, ResponsiveConfig, MobileOverrides, PWAConfig, PWAIcon, CacheStrategy, OfflineConfig, OfflineRoute, GestureType, GestureConfig, GestureContext, MobileComponentConfig, SpecGestureConfig, SwipeGestureConfig, PinchGestureConfig, LongPressGestureConfig, TouchInteraction, TouchTargetConfig, } from '@object-ui/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACtG,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,KAAK,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAGpE,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,OAAO,EACP,aAAa,EACb,aAAa,EACb,YAAY,EACZ,WAAW,EACX,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,KAAK,oBAAoB,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrH,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACtG,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,KAAK,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAGpE,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,OAAO,EACP,aAAa,EACb,aAAa,EACb,YAAY,EACZ,WAAW,EACX,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -28,4 +28,8 @@ export { MobileProvider } from './MobileProvider';
 export { ResponsiveContainer } from './ResponsiveContainer';
 export { generatePWAManifest } from './pwa';
 export { registerServiceWorker } from './serviceWorker';
+export { createOfflineQueue, IndexedDbOfflineQueue, MemoryOfflineQueue, generateOpId, } from './offlineQueue';
+export { createOfflineDataSource, } from './createOfflineDataSource';
+export { useOfflineSync } from './useOfflineSync';
+export { getServiceWorkerSource, requestBackgroundSync, } from './serviceWorkerSource';
 export { BREAKPOINTS, resolveResponsiveValue } from './breakpoints';

package/dist/offlineQueue.d.ts

@@ -0,0 +1,78 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * IndexedDB-backed offline write queue.
+ *
+ * Designed to back a `createOfflineDataSource()` wrapper: when the network
+ * is unavailable the wrapper enqueues mutations here, then replays them in
+ * insertion order when connectivity is restored (or a Service Worker
+ * `sync` event fires).
+ *
+ * The implementation is dependency-free and uses raw IndexedDB so it works
+ * inside both pages and Service Workers. Falls back to an in-memory store
+ * when IndexedDB is unavailable (e.g. during SSR or in unit tests without
+ * `fake-indexeddb`).
+ */
+/** A queued mutation. */
+export interface OfflineOperation {
+    /** Auto-generated stable id (uuid-like). */
+    id: string;
+    /** Logical op type. */
+    op: 'create' | 'update' | 'delete' | 'custom';
+    /** Object/collection the mutation targets. */
+    object: string;
+    /** Optional record id (required for update/delete). */
+    recordId?: string | number;
+    /** Mutation payload. */
+    payload?: any;
+    /**
+     * Optional ObjectQL FilterAST snapshot of the *expected* current row
+     * state. Used by conflict-resolution to detect "stale write" conflicts
+     * when the server row has changed in the interim.
+     *
+     * The shape is left as `unknown` here so this package doesn't need a
+     * runtime dep on `@objectstack/spec` — consumers may pass through any
+     * serializable structure.
+     */
+    expectFilter?: unknown;
+    /** Wall-clock millis when the op was enqueued. */
+    enqueuedAt: number;
+    /** Number of replay attempts so far. */
+    attempts: number;
+    /** Last error message, if any. */
+    lastError?: string;
+}
+/** Backend-agnostic queue contract. */
+export interface OfflineQueueBackend {
+    enqueue(op: OfflineOperation): Promise<void>;
+    list(): Promise<OfflineOperation[]>;
+    remove(id: string): Promise<void>;
+    update(op: OfflineOperation): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Generate a short, sortable id without external deps. */
+export declare function generateOpId(): string;
+/** IndexedDB-backed queue. Constructor returns a backend usable everywhere. */
+export declare class IndexedDbOfflineQueue implements OfflineQueueBackend {
+    private dbPromise;
+    private getDb;
+    private tx;
+    enqueue(op: OfflineOperation): Promise<void>;
+    update(op: OfflineOperation): Promise<void>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    list(): Promise<OfflineOperation[]>;
+}
+/** In-memory fallback. Used in SSR / tests / when IndexedDB is blocked. */
+export declare class MemoryOfflineQueue implements OfflineQueueBackend {
+    private rows;
+    enqueue(op: OfflineOperation): Promise<void>;
+    update(op: OfflineOperation): Promise<void>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    list(): Promise<OfflineOperation[]>;
+}
+/** Choose the best available backend for the current runtime. */
+export declare function createOfflineQueue(): OfflineQueueBackend;
+//# sourceMappingURL=offlineQueue.d.ts.map

package/dist/offlineQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offlineQueue.d.ts","sourceRoot":"","sources":["../src/offlineQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,yBAAyB;AACzB,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,uBAAuB;IACvB,EAAE,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC9C,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,wBAAwB;IACxB,OAAO,CAAC,EAAE,GAAG,CAAC;IACd;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,2DAA2D;AAC3D,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAsBD,+EAA+E;AAC/E,qBAAa,qBAAsB,YAAW,mBAAmB;IAC/D,OAAO,CAAC,SAAS,CAAqC;IACtD,OAAO,CAAC,KAAK;YAIC,EAAE;IAUV,OAAO,CAAC,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAC5C,MAAM,CAAC,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAW1C;AAED,2EAA2E;AAC3E,qBAAa,kBAAmB,YAAW,mBAAmB;IAC5D,OAAO,CAAC,IAAI,CAAuC;IAC7C,OAAO,CAAC,EAAE,EAAE,gBAAgB;IAC5B,MAAM,CAAC,EAAE,EAAE,gBAAgB;IAC3B,MAAM,CAAC,EAAE,EAAE,MAAM;IACjB,KAAK;IACL,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAG1C;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,IAAI,mBAAmB,CAGxD"}

package/dist/offlineQueue.js

@@ -0,0 +1,110 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * IndexedDB-backed offline write queue.
+ *
+ * Designed to back a `createOfflineDataSource()` wrapper: when the network
+ * is unavailable the wrapper enqueues mutations here, then replays them in
+ * insertion order when connectivity is restored (or a Service Worker
+ * `sync` event fires).
+ *
+ * The implementation is dependency-free and uses raw IndexedDB so it works
+ * inside both pages and Service Workers. Falls back to an in-memory store
+ * when IndexedDB is unavailable (e.g. during SSR or in unit tests without
+ * `fake-indexeddb`).
+ */
+/** Generate a short, sortable id without external deps. */
+export function generateOpId() {
+    const ts = Date.now().toString(36);
+    const rand = Math.random().toString(36).slice(2, 10);
+    return `op-${ts}-${rand}`;
+}
+const DB_NAME = 'objectui-offline';
+const STORE = 'queue';
+const DB_VERSION = 1;
+/** Open the IndexedDB database, creating the queue object store on first run. */
+function openDb() {
+    return new Promise((resolve, reject) => {
+        const req = indexedDB.open(DB_NAME, DB_VERSION);
+        req.onupgradeneeded = () => {
+            const db = req.result;
+            if (!db.objectStoreNames.contains(STORE)) {
+                const store = db.createObjectStore(STORE, { keyPath: 'id' });
+                store.createIndex('enqueuedAt', 'enqueuedAt', { unique: false });
+            }
+        };
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(req.error);
+    });
+}
+/** IndexedDB-backed queue. Constructor returns a backend usable everywhere. */
+export class IndexedDbOfflineQueue {
+    constructor() {
+        Object.defineProperty(this, "dbPromise", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    getDb() {
+        if (!this.dbPromise)
+            this.dbPromise = openDb();
+        return this.dbPromise;
+    }
+    async tx(mode, fn) {
+        const db = await this.getDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(STORE, mode);
+            const store = tx.objectStore(STORE);
+            const req = fn(store);
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async enqueue(op) { await this.tx('readwrite', (s) => s.add(op)); }
+    async update(op) { await this.tx('readwrite', (s) => s.put(op)); }
+    async remove(id) { await this.tx('readwrite', (s) => s.delete(id)); }
+    async clear() { await this.tx('readwrite', (s) => s.clear()); }
+    async list() {
+        const db = await this.getDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(STORE, 'readonly');
+            const store = tx.objectStore(STORE);
+            const idx = store.index('enqueuedAt');
+            const req = idx.getAll();
+            req.onsuccess = () => resolve(req.result ?? []);
+            req.onerror = () => reject(req.error);
+        });
+    }
+}
+/** In-memory fallback. Used in SSR / tests / when IndexedDB is blocked. */
+export class MemoryOfflineQueue {
+    constructor() {
+        Object.defineProperty(this, "rows", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    async enqueue(op) { this.rows.set(op.id, op); }
+    async update(op) { this.rows.set(op.id, op); }
+    async remove(id) { this.rows.delete(id); }
+    async clear() { this.rows.clear(); }
+    async list() {
+        return [...this.rows.values()].sort((a, b) => a.enqueuedAt - b.enqueuedAt);
+    }
+}
+/** Choose the best available backend for the current runtime. */
+export function createOfflineQueue() {
+    if (typeof indexedDB === 'undefined')
+        return new MemoryOfflineQueue();
+    try {
+        return new IndexedDbOfflineQueue();
+    }
+    catch {
+        return new MemoryOfflineQueue();
+    }
+}

package/dist/serviceWorkerSource.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * Generates a Service Worker source string with offline support for
+ * ObjectUI apps. The output is intended to be written to a file at the
+ * web root (e.g. `/service-worker.js`) by the application's build
+ * pipeline; it is *not* shipped at runtime by the mobile package itself.
+ *
+ * The generated SW does three things:
+ *  1. Caches the application shell on install (`cache-first` strategy).
+ *  2. Falls back to network-first for API calls, so reads are fresh
+ *     when online and degrade to cached responses when offline.
+ *  3. Listens for `sync` events with tag `objectui-offline-queue` and
+ *     posts a `REPLAY_QUEUE` message to all clients so the running
+ *     pages can flush their queues from the foreground.
+ */
+export interface ServiceWorkerSourceOptions {
+    /** Cache name; bump to invalidate on deploy. */
+    cacheName?: string;
+    /** Application shell URLs to pre-cache on install. */
+    precache?: string[];
+    /** URL prefix that identifies API requests (network-first). */
+    apiPrefix?: string;
+    /** Background-sync tag name. */
+    syncTag?: string;
+}
+/**
+ * Build a Service Worker JavaScript source string. Customize the cache
+ * version, app shell, and sync tag via `options`.
+ */
+export declare function getServiceWorkerSource(options?: ServiceWorkerSourceOptions): string;
+/**
+ * Request a one-shot background sync. The page should call this after
+ * enqueuing offline work so the browser will wake the SW when the
+ * connection returns. Returns false if Background Sync is unsupported.
+ */
+export declare function requestBackgroundSync(tag?: string): Promise<boolean>;
+//# sourceMappingURL=serviceWorkerSource.d.ts.map

package/dist/serviceWorkerSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceWorkerSource.d.ts","sourceRoot":"","sources":["../src/serviceWorkerSource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,0BAA0B;IACzC,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,CA+DvF;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,SAA2B,GAAG,OAAO,CAAC,OAAO,CAAC,CAK5F"}

package/dist/serviceWorkerSource.js

@@ -0,0 +1,103 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * Generates a Service Worker source string with offline support for
+ * ObjectUI apps. The output is intended to be written to a file at the
+ * web root (e.g. `/service-worker.js`) by the application's build
+ * pipeline; it is *not* shipped at runtime by the mobile package itself.
+ *
+ * The generated SW does three things:
+ *  1. Caches the application shell on install (`cache-first` strategy).
+ *  2. Falls back to network-first for API calls, so reads are fresh
+ *     when online and degrade to cached responses when offline.
+ *  3. Listens for `sync` events with tag `objectui-offline-queue` and
+ *     posts a `REPLAY_QUEUE` message to all clients so the running
+ *     pages can flush their queues from the foreground.
+ */
+/**
+ * Build a Service Worker JavaScript source string. Customize the cache
+ * version, app shell, and sync tag via `options`.
+ */
+export function getServiceWorkerSource(options = {}) {
+    const cacheName = options.cacheName ?? 'objectui-shell-v1';
+    const precache = options.precache ?? ['/', '/index.html'];
+    const apiPrefix = options.apiPrefix ?? '/api/';
+    const syncTag = options.syncTag ?? 'objectui-offline-queue';
+    return `// Auto-generated by @object-ui/mobile getServiceWorkerSource()
+const CACHE = ${JSON.stringify(cacheName)};
+const PRECACHE = ${JSON.stringify(precache)};
+const API_PREFIX = ${JSON.stringify(apiPrefix)};
+const SYNC_TAG = ${JSON.stringify(syncTag)};
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(caches.open(CACHE).then((c) => c.addAll(PRECACHE)));
+  self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+  event.waitUntil(
+    caches.keys().then((keys) =>
+      Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k))),
+    ),
+  );
+  self.clients.claim();
+});
+
+self.addEventListener('fetch', (event) => {
+  const req = event.request;
+  if (req.method !== 'GET') return;
+  const url = new URL(req.url);
+
+  if (url.pathname.startsWith(API_PREFIX)) {
+    // Network-first for API
+    event.respondWith(
+      fetch(req).then((res) => {
+        const copy = res.clone();
+        caches.open(CACHE).then((c) => c.put(req, copy));
+        return res;
+      }).catch(() => caches.match(req).then((cached) => cached || Response.error())),
+    );
+    return;
+  }
+
+  // Cache-first for shell assets
+  event.respondWith(
+    caches.match(req).then((cached) => cached || fetch(req).then((res) => {
+      const copy = res.clone();
+      caches.open(CACHE).then((c) => c.put(req, copy));
+      return res;
+    })),
+  );
+});
+
+self.addEventListener('sync', (event) => {
+  if (event.tag !== SYNC_TAG) return;
+  event.waitUntil((async () => {
+    const all = await self.clients.matchAll({ includeUncontrolled: true });
+    for (const client of all) {
+      client.postMessage({ type: 'REPLAY_QUEUE', tag: SYNC_TAG });
+    }
+  })());
+});
+`;
+}
+/**
+ * Request a one-shot background sync. The page should call this after
+ * enqueuing offline work so the browser will wake the SW when the
+ * connection returns. Returns false if Background Sync is unsupported.
+ */
+export async function requestBackgroundSync(tag = 'objectui-offline-queue') {
+    if (typeof navigator === 'undefined')
+        return false;
+    const reg = await navigator.serviceWorker?.ready;
+    if (!reg || !reg.sync)
+        return false;
+    try {
+        await reg.sync.register(tag);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/useOfflineSync.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * React hook that subscribes to an `OfflineDataSource`, exposing the current
+ * online/offline status and the pending queue for status-bar / banner UIs.
+ */
+import type { OfflineDataSource } from './createOfflineDataSource';
+import type { OfflineOperation } from './offlineQueue';
+export interface OfflineSyncState {
+    /** True if the browser reports `navigator.onLine`. */
+    isOnline: boolean;
+    /** Pending ops, oldest first. */
+    pending: OfflineOperation[];
+    /** True while a replay is in-flight. */
+    isReplaying: boolean;
+    /** Manually trigger a replay. */
+    replay: () => Promise<void>;
+    /** Drop a queued op without replaying it. */
+    drop: (opId: string) => Promise<void>;
+    /** Drop everything. */
+    clear: () => Promise<void>;
+}
+/**
+ * Subscribe to a wrapped offline DataSource. Auto-replays the queue
+ * whenever the browser fires `online`.
+ */
+export declare function useOfflineSync(source: OfflineDataSource): OfflineSyncState;
+//# sourceMappingURL=useOfflineSync.d.ts.map

package/dist/useOfflineSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOfflineSync.d.ts","sourceRoot":"","sources":["../src/useOfflineSync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,QAAQ,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,iCAAiC;IACjC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,6CAA6C;IAC7C,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,uBAAuB;IACvB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,iBAAiB,GAAG,gBAAgB,CA+C1E"}

package/dist/useOfflineSync.js

@@ -0,0 +1,61 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * React hook that subscribes to an `OfflineDataSource`, exposing the current
+ * online/offline status and the pending queue for status-bar / banner UIs.
+ */
+import { useEffect, useState, useCallback } from 'react';
+/**
+ * Subscribe to a wrapped offline DataSource. Auto-replays the queue
+ * whenever the browser fires `online`.
+ */
+export function useOfflineSync(source) {
+    const [pending, setPending] = useState([]);
+    const [isOnline, setOnline] = useState(() => typeof navigator === 'undefined' ? true : navigator.onLine !== false);
+    const [isReplaying, setReplaying] = useState(false);
+    const refresh = useCallback(async () => {
+        try {
+            setPending(await source.pending());
+        }
+        catch {
+            setPending([]);
+        }
+    }, [source]);
+    const replay = useCallback(async () => {
+        setReplaying(true);
+        try {
+            await source.replay();
+        }
+        finally {
+            setReplaying(false);
+            await refresh();
+        }
+    }, [source, refresh]);
+    const drop = useCallback(async (opId) => {
+        await source.drop(opId);
+        await refresh();
+    }, [source, refresh]);
+    const clear = useCallback(async () => {
+        await source.clear();
+        await refresh();
+    }, [source, refresh]);
+    // Initial load + listen for online/offline transitions.
+    useEffect(() => {
+        refresh();
+        if (typeof window === 'undefined')
+            return;
+        const onOnline = () => {
+            setOnline(true);
+            void replay();
+        };
+        const onOffline = () => setOnline(false);
+        window.addEventListener('online', onOnline);
+        window.addEventListener('offline', onOffline);
+        return () => {
+            window.removeEventListener('online', onOnline);
+            window.removeEventListener('offline', onOffline);
+        };
+    }, [refresh, replay]);
+    return { isOnline, pending, isReplaying, replay, drop, clear };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/mobile",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "type": "module",
   "license": "MIT",
   "description": "Mobile optimization for Object UI with responsive components, PWA support, and touch gesture handling.",
@@ -30,7 +30,7 @@
     "react": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@object-ui/types": "3.3.2"
+    "@object-ui/types": "3.4.0"
   },
   "devDependencies": {
     "@types/react": "19.2.14",