@dhis2/app-service-offline 2.10.0 → 2.12.0

package/build/es/lib/offline-interface.js

@@ -0,0 +1,65 @@
+import { useAlert } from '@dhis2/app-service-alerts';
+import PropTypes from 'prop-types';
+import React, { createContext, useContext } from 'react';
+// This is to prevent 'offlineInterface could be null' type-checking errors
+const noopOfflineInterface = {
+  pwaEnabled: false,
+  init: () => () => null,
+  startRecording: async () => undefined,
+  getCachedSections: async () => [],
+  removeSection: async () => false
+};
+const OfflineInterfaceContext = /*#__PURE__*/createContext(noopOfflineInterface);
+
+/**
+ * Receives an OfflineInterface instance as a prop (presumably from the app
+ * adapter) and provides it as context for other offline tools.
+ *
+ * On mount, it initializes the offline interface, which (among other things)
+ * checks for service worker updates and, if updates are ready, prompts the
+ * user with an alert to skip waiting and reload the page to use new content.
+ */
+export function OfflineInterfaceProvider({
+  offlineInterface,
+  children
+}) {
+  const {
+    show
+  } = useAlert(({
+    message
+  }) => message, ({
+    action,
+    onConfirm
+  }) => ({
+    actions: [{
+      label: action,
+      onClick: onConfirm
+    }],
+    permanent: true
+  }));
+  React.useEffect(() => {
+    // Init returns a tear-down function
+    return offlineInterface.init({
+      promptUpdate: show
+    });
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return /*#__PURE__*/React.createElement(OfflineInterfaceContext.Provider, {
+    value: offlineInterface
+  }, children);
+}
+OfflineInterfaceProvider.propTypes = {
+  children: PropTypes.node,
+  offlineInterface: PropTypes.shape({
+    init: PropTypes.func
+  })
+};
+export function useOfflineInterface() {
+  const offlineInterface = useContext(OfflineInterfaceContext);
+
+  if (offlineInterface === undefined) {
+    throw new Error('Offline interface context not found. If this app is using the app platform, make sure `pwa: { enabled: true }` is in d2.config.js. If this is not a platform app, make sure your app is wrapped with an app-runtime <Provider> or an <OfflineProvider> from app-service-offline.');
+  }
+
+  return offlineInterface;
+}

package/build/es/lib/offline-provider.js

@@ -0,0 +1,40 @@
+import PropTypes from 'prop-types';
+import React from 'react';
+import { CacheableSectionProvider } from './cacheable-section-state';
+import { OfflineInterfaceProvider } from './offline-interface';
+
+/** A context provider for all the relevant offline contexts */
+export function OfflineProvider({
+  offlineInterface,
+  children
+}) {
+  // If an offline interface is not provided, or if one is provided and PWA
+  // is not enabled, skip adding context providers
+  if (!offlineInterface) {
+    return /*#__PURE__*/React.createElement(React.Fragment, null, children);
+  } // If PWA is not enabled, just init interface to make sure new SW gets
+  // activated with code that unregisters SW. Not technically necessary if a
+  // killswitch SW takes over, but the killswitch may not always be in use.
+  // Then, skip adding any context
+
+
+  if (!offlineInterface.pwaEnabled) {
+    offlineInterface.init({
+      promptUpdate: ({
+        onConfirm
+      }) => onConfirm()
+    });
+    return /*#__PURE__*/React.createElement(React.Fragment, null, children);
+  }
+
+  return /*#__PURE__*/React.createElement(OfflineInterfaceProvider, {
+    offlineInterface: offlineInterface
+  }, /*#__PURE__*/React.createElement(CacheableSectionProvider, null, children));
+}
+OfflineProvider.propTypes = {
+  children: PropTypes.node,
+  offlineInterface: PropTypes.shape({
+    init: PropTypes.func,
+    pwaEnabled: PropTypes.bool
+  })
+};

package/build/es/types.js

@@ -1 +0,0 @@
-// todo

package/build/es/utils/__tests__/render-counter.test.js

@@ -0,0 +1,40 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import React from 'react';
+import { RenderCounter, resetRenderCounts } from '../render-counter';
+const renderCounts = {};
+export const Rerenderer = () => {
+  const [, setState] = React.useState(true);
+
+  const toggleState = () => setState(prevState => !prevState);
+
+  return /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement("button", {
+    onClick: toggleState,
+    role: "button"
+  }), /*#__PURE__*/React.createElement(RenderCounter, {
+    id: 'rc1',
+    countsObj: renderCounts
+  }));
+};
+afterEach(() => {
+  resetRenderCounts(renderCounts);
+});
+it('increments the counter when rerendered', () => {
+  render( /*#__PURE__*/React.createElement(Rerenderer, null));
+  const {
+    getByTestId,
+    getByRole
+  } = screen;
+  expect(getByTestId('rc1')).toHaveTextContent('1');
+  act(() => {
+    fireEvent.click(getByRole('button'));
+  });
+  expect(getByTestId('rc1')).toHaveTextContent('2');
+  act(() => {
+    fireEvent.click(getByRole('button'));
+  });
+  expect(getByTestId('rc1')).toHaveTextContent('3');
+});
+it('resets the render counter successfully', () => {
+  render( /*#__PURE__*/React.createElement(Rerenderer, null));
+  expect(screen.getByTestId('rc1')).toHaveTextContent('1');
+});

package/build/es/utils/render-counter.js

@@ -0,0 +1,11 @@
+import React from 'react';
+export const RenderCounter = ({
+  id,
+  countsObj
+}) => {
+  if (!(id in countsObj)) countsObj[id] = 0;
+  return /*#__PURE__*/React.createElement("div", {
+    "data-testid": id
+  }, ++countsObj[id]);
+};
+export const resetRenderCounts = renderCounts => Object.keys(renderCounts).forEach(key => renderCounts[key] = 0);

package/build/es/utils/test-mocks.js

@@ -0,0 +1,30 @@
+export const successfulRecordingMock = jest.fn().mockImplementation(async ({
+  onStarted,
+  onCompleted
+} = {}) => {
+  // in 100ms, call 'onStarted' callback (allows 'pending' state)
+  if (onStarted) setTimeout(onStarted, 100); // in 200ms, call 'onCompleted' callback
+
+  if (onCompleted) setTimeout(onCompleted, 200); // resolve
+
+  return Promise.resolve();
+});
+export const errorRecordingMock = jest.fn().mockImplementation(({
+  onStarted,
+  onError
+} = {}) => {
+  // in 100ms, call 'onStarted' callback (allows 'pending' state)
+  if (onStarted) setTimeout(onStarted, 100); // in 200ms, call 'onError'
+
+  setTimeout(() => onError(new Error('test err')), 200); // resolve to signal successful initiation
+
+  return Promise.resolve();
+});
+export const failedMessageRecordingMock = jest.fn().mockRejectedValue(new Error('Failed message'));
+export const mockOfflineInterface = {
+  pwaEnabled: true,
+  init: jest.fn(),
+  startRecording: successfulRecordingMock,
+  getCachedSections: jest.fn().mockResolvedValue([]),
+  removeSection: jest.fn().mockResolvedValue(true)
+};

package/build/types/index.d.ts

@@ -1 +1,5 @@
+export { OfflineProvider } from './lib/offline-provider';
+export { CacheableSection, useCacheableSection } from './lib/cacheable-section';
+export { useCachedSections } from './lib/cacheable-section-state';
 export { useOnlineStatus } from './lib/online-status';
+export { clearSensitiveCaches } from './lib/clear-sensitive-caches';

package/build/types/lib/cacheable-section-state.d.ts

@@ -0,0 +1,66 @@
+import PropTypes from 'prop-types';
+import React from 'react';
+import { GlobalStateStore, RecordingState } from '../types';
+interface CachedSectionsById {
+    [index: string]: {
+        lastUpdated: Date;
+    };
+}
+/**
+ * Create a store for Cacheable Section state.
+ * Expected to be used in app adapter
+ */
+export declare function createCacheableSectionStore(): GlobalStateStore;
+/**
+ * Provides context for a global state context which will track cached
+ * sections' status and cacheable sections' recording states, which will
+ * determine how that component will render. The provider will be a part of
+ * the OfflineProvider.
+ */
+export declare function CacheableSectionProvider({ children, }: {
+    children: React.ReactNode;
+}): JSX.Element;
+export declare namespace CacheableSectionProvider {
+    var propTypes: {
+        children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+    };
+}
+interface RecordingStateControls {
+    recordingState: RecordingState;
+    setRecordingState: (newState: RecordingState) => void;
+    removeRecordingState: () => void;
+}
+/**
+ * Uses an optimized global state to manage 'recording state' values without
+ * unnecessarily rerendering all consuming components
+ *
+ * @param {String} id - ID of the cacheable section to track
+ * @returns {Object} { recordingState: String, setRecordingState: Function, removeRecordingState: Function}
+ */
+export declare function useRecordingState(id: string): RecordingStateControls;
+interface CachedSectionsControls {
+    cachedSections: CachedSectionsById;
+    removeById: (id: string) => Promise<boolean>;
+    syncCachedSections: () => Promise<void>;
+}
+/**
+ * Uses global state to manage an object of cached sections' statuses
+ *
+ * @returns {Object} { cachedSections: Object, removeSection: Function }
+ */
+export declare function useCachedSections(): CachedSectionsControls;
+interface CachedSectionControls {
+    lastUpdated: Date;
+    isCached: boolean;
+    remove: () => Promise<boolean>;
+    syncCachedSections: () => Promise<void>;
+}
+/**
+ * Uses global state to manage the cached status of just one section, which
+ * prevents unnecessary rerenders of consuming components
+ *
+ * @param {String} id
+ * @returns {Object} { lastUpdated: Date, remove: Function }
+ */
+export declare function useCachedSection(id: string): CachedSectionControls;
+export {};

package/build/types/lib/cacheable-section.d.ts

@@ -0,0 +1,52 @@
+import PropTypes from 'prop-types';
+import React from 'react';
+import { RecordingState } from '../types';
+interface CacheableSectionStartRecordingOptions {
+    recordingTimeoutDelay?: number;
+    onStarted?: () => void;
+    onCompleted?: () => void;
+    onError?: (err: Error) => void;
+}
+export declare type CacheableSectionStartRecording = (options?: CacheableSectionStartRecordingOptions) => Promise<any>;
+interface CacheableSectionControls {
+    recordingState: RecordingState;
+    startRecording: CacheableSectionStartRecording;
+    lastUpdated: Date | undefined;
+    isCached: boolean;
+    remove: () => Promise<boolean>;
+}
+/**
+ * Returns the main controls for a cacheable section and manages recording
+ * state, which affects the render state of the CacheableSection component.
+ * Also returns the cached status of the section, which come straight from
+ * the `useCachedSection` hook.
+ *
+ * @param {String} id
+ * @returns {Object}
+ */
+export declare function useCacheableSection(id: string): CacheableSectionControls;
+interface CacheableSectionProps {
+    id: string;
+    loadingMask: JSX.Element;
+    children: React.ReactNode;
+}
+/**
+ * Used to wrap the relevant component to be recorded and saved offline.
+ * Depending on the recording state of the section, this wrapper will
+ * render its children, not render its children while recording is pending,
+ * or RErerender the chilren to force data fetching to record by the service
+ * worker.
+ *
+ * During recording, a loading mask provided by props is also rendered that is
+ * intended to prevent other interaction with the app that might interfere
+ * with the recording process.
+ */
+export declare function CacheableSection({ id, loadingMask, children, }: CacheableSectionProps): JSX.Element;
+export declare namespace CacheableSection {
+    var propTypes: {
+        id: PropTypes.Validator<string>;
+        children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        loadingMask: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+    };
+}
+export {};

package/build/types/lib/clear-sensitive-caches.d.ts

@@ -0,0 +1,16 @@
+export declare const SECTIONS_DB = "sections-db";
+export declare const SECTIONS_STORE = "sections-store";
+declare global {
+    interface IDBFactory {
+        databases(): Promise<[{
+            name: string;
+            version: number;
+        }]>;
+    }
+}
+/**
+ * Used to clear caches and 'sections-db' IndexedDB when a user logs out or a
+ * different user logs in to prevent someone from accessing a different user's
+ * caches. Should be able to be used in a non-PWA app.
+ */
+export declare function clearSensitiveCaches(dbName?: string): Promise<any>;

package/build/types/lib/global-state-service.d.ts

@@ -0,0 +1,16 @@
+import PropTypes from 'prop-types';
+import React from 'react';
+import { GlobalStateStore, GlobalStateStoreMutateMethod, GlobalStateMutation, GlobalStateStoreMutationCreator } from '../types';
+export declare const createStore: (initialState?: {}) => GlobalStateStore;
+export declare const GlobalStateProvider: {
+    ({ store, children, }: {
+        store: GlobalStateStore;
+        children: React.ReactNode;
+    }): JSX.Element;
+    propTypes: {
+        children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        store: PropTypes.Requireable<PropTypes.InferProps<{}>>;
+    };
+};
+export declare const useGlobalState: (selector?: (state: any) => any) => [any, GlobalStateStoreMutateMethod];
+export declare function useGlobalStateMutation<Type>(mutationCreator: GlobalStateStoreMutationCreator<Type>): GlobalStateMutation<Type>;

package/build/types/lib/offline-interface.d.ts

@@ -0,0 +1,26 @@
+import PropTypes from 'prop-types';
+import React from 'react';
+import { OfflineInterface } from '../types';
+interface OfflineInterfaceProviderInput {
+    offlineInterface: OfflineInterface;
+    children: React.ReactNode;
+}
+/**
+ * Receives an OfflineInterface instance as a prop (presumably from the app
+ * adapter) and provides it as context for other offline tools.
+ *
+ * On mount, it initializes the offline interface, which (among other things)
+ * checks for service worker updates and, if updates are ready, prompts the
+ * user with an alert to skip waiting and reload the page to use new content.
+ */
+export declare function OfflineInterfaceProvider({ offlineInterface, children, }: OfflineInterfaceProviderInput): JSX.Element;
+export declare namespace OfflineInterfaceProvider {
+    var propTypes: {
+        children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        offlineInterface: PropTypes.Requireable<PropTypes.InferProps<{
+            init: PropTypes.Requireable<(...args: any[]) => any>;
+        }>>;
+    };
+}
+export declare function useOfflineInterface(): OfflineInterface;
+export {};

package/build/types/lib/offline-provider.d.ts

@@ -0,0 +1,19 @@
+import PropTypes from 'prop-types';
+import React from 'react';
+import { OfflineInterface } from '../types';
+interface OfflineProviderInput {
+    offlineInterface?: OfflineInterface;
+    children?: React.ReactNode;
+}
+/** A context provider for all the relevant offline contexts */
+export declare function OfflineProvider({ offlineInterface, children, }: OfflineProviderInput): JSX.Element;
+export declare namespace OfflineProvider {
+    var propTypes: {
+        children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        offlineInterface: PropTypes.Requireable<PropTypes.InferProps<{
+            init: PropTypes.Requireable<(...args: any[]) => any>;
+            pwaEnabled: PropTypes.Requireable<boolean>;
+        }>>;
+    };
+}
+export {};

package/build/types/types.d.ts

@@ -0,0 +1,50 @@
+export declare type RecordingState = 'default' | 'pending' | 'error' | 'recording';
+export interface GlobalStateStoreMutation {
+    (state: any): any;
+}
+export interface GlobalStateStoreMutationCreator<Type> {
+    (...args: Type[]): GlobalStateStoreMutation;
+}
+export interface GlobalStateMutation<Type> {
+    (...args: Type[]): void;
+}
+export interface GlobalStateStoreMutateMethod {
+    (mutation: GlobalStateStoreMutation): void;
+}
+export interface GlobalStateStore {
+    getState: () => any;
+    subscribe: (callback: (state: any) => void) => void;
+    unsubscribe: (callback: (state: any) => void) => void;
+    mutate: GlobalStateStoreMutateMethod;
+}
+interface PromptUpdate {
+    (params: {
+        message: string;
+        action: string;
+        onConfirm: () => void;
+    }): void;
+}
+interface StartRecording {
+    (params: {
+        sectionId: string;
+        recordingTimeoutDelay: number;
+        onStarted: () => void;
+        onCompleted: () => void;
+        onError: (err: Error) => void;
+    }): Promise<undefined>;
+}
+export interface IndexedDBCachedSection {
+    sectionId: string;
+    lastUpdated: Date;
+    requests: number;
+}
+export interface OfflineInterface {
+    readonly pwaEnabled: boolean;
+    init: (params: {
+        promptUpdate: PromptUpdate;
+    }) => () => void;
+    startRecording: StartRecording;
+    getCachedSections: () => Promise<IndexedDBCachedSection[]>;
+    removeSection: (id: string) => Promise<boolean>;
+}
+export {};