@lowdefy/shell 3.23.2 → 7.2.0

package/src/dev/tab/reloadApp.test.js

@@ -0,0 +1,115 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { jest } from '@jest/globals';
+import { act, screen } from '@testing-library/react-native';
+
+import getShownPage from './getShownPage.js';
+import reloadApp from './reloadApp.js';
+import renderPageScreen from '../../test/renderPageScreen.js';
+import { createRoot } from '../../test/fixtures.js';
+
+// The native stack's header height, which a Screen's headerBottom pins under on iOS.
+jest.mock('expo-router/native-stack', () => ({ useAnimatedHeaderHeight: () => 0 }));
+jest.mock('react-native-safe-area-context', () => ({
+  useSafeAreaInsets: () => ({ top: 0, right: 0, bottom: 34, left: 0 }),
+}));
+
+jest.mock('expo-router', () => ({
+  DarkTheme: { fonts: {} },
+  DefaultTheme: { fonts: {} },
+  ThemeProvider: ({ children }) => children,
+  router: { back: jest.fn(), canGoBack: () => false },
+  useFocusEffect: (effect) => {
+    const { useEffect: useReactEffect } = jest.requireActual('react');
+    useReactEffect(effect, [effect]);
+  },
+  useIsFocused: () => true,
+  useNavigation: () => ({ setOptions: jest.fn() }),
+  useRoute: () => ({ key: 'route-1' }),
+}));
+
+function todayPage(greeting) {
+  return {
+    id: 'page:today',
+    pageId: 'today',
+    blockId: 'today',
+    type: 'Screen',
+    properties: { title: 'Today' },
+    slots: {
+      content: {
+        blocks: [
+          {
+            id: 'block:today:greeting:0',
+            blockId: 'greeting',
+            type: 'Box',
+            properties: { content: greeting },
+          },
+        ],
+      },
+    },
+  };
+}
+
+// A dev root: its pages have no hash, so the shell fetches them on each visit.
+async function renderDevPage() {
+  const { server, session } = await renderPageScreen({
+    path: 'today',
+    root: createRoot({
+      pageIndex: [{ path: 'today', pageId: 'today', hash: null, typesKey: 'screen' }],
+      typeSets: {
+        screen: {
+          blocks: [
+            { type: 'Box', package: '@lowdefy/blocks-native', version: 7 },
+            { type: 'Screen', package: '@lowdefy/blocks-native', version: 7 },
+          ],
+        },
+      },
+    }),
+    pages: { today: { pageConfig: todayPage('Hello'), etag: '"p1"' } },
+  });
+  await screen.findByText('Hello');
+  return { server, session };
+}
+
+test('a reload refetches the root and the page on screen, and rebuilds it with empty state', async () => {
+  const { server, session } = await renderDevPage();
+  const before = session.getState().lowdefy;
+  const shown = getShownPage(before);
+  // The screen's page context is keyed by its route instance.
+  expect(shown).toEqual({ pageId: 'today', pathParams: {}, instanceKey: 'page:today@route-1' });
+  before.contexts[shown.instanceKey]._internal.State.set('typed', 'Quarterly');
+  expect(before.contexts[shown.instanceKey].state.typed).toBe('Quarterly');
+
+  server.state.pages.today = { pageConfig: todayPage('Hello again'), etag: '"p2"' };
+  server.state.rootEtag = '"r2"';
+  server.fetch.mockClear();
+  await act(async () => {
+    await reloadApp({ session });
+  });
+
+  const paths = server.fetch.mock.calls.map(([url]) => new URL(url).pathname);
+  // The rebuilt screen revalidates its page, as every screen does after a rebuild, so a screen
+  // under the one shown gets its new version too: the version reloadApp fetched is current.
+  expect(paths).toEqual(['/api/page/today', '/api/mobile/root', '/api/user', '/api/page/today']);
+  const revalidation = server.fetch.mock.calls.at(-1)[1];
+  expect(revalidation.headers).toEqual({ 'If-None-Match': '"p2"' });
+  expect(await screen.findByText('Hello again')).toBeTruthy();
+  expect(session.getCurrentPath()).toBe('/today');
+  const after = session.getState().lowdefy;
+  expect(after).not.toBe(before);
+  expect(after.contexts[shown.instanceKey].state.typed).toBeUndefined();
+});

package/src/device/DeviceHosts.js

@@ -0,0 +1,32 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import React from 'react';
+
+import device from './device.js';
+
+// The views device features open over the app (the ScanCode sheet), mounted once at the root.
+function DeviceHosts() {
+  return (
+    <>
+      {device.hosts.map((Host) => (
+        <Host key={Host.name} />
+      ))}
+    </>
+  );
+}
+
+export default DeviceHosts;

package/src/device/basic/createFilesFeature.js

@@ -0,0 +1,41 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import * as DocumentPicker from 'expo-document-picker';
+
+import toPickedFile from './toPickedFile.js';
+
+/**
+ * The files device feature: picks files from Files (iOS) or the document picker (Android), copied
+ * into the app's cache so they can be read and uploaded. [] when cancelled.
+ */
+function createFilesFeature() {
+  return {
+    async pick({ base64 = false, multiple = false, types }) {
+      const result = await DocumentPicker.getDocumentAsync({
+        copyToCacheDirectory: true,
+        multiple,
+        type: types ?? '*/*',
+      });
+      if (result.canceled) {
+        return [];
+      }
+      return Promise.all(result.assets.map((asset) => toPickedFile({ asset, base64 })));
+    },
+  };
+}
+
+export default createFilesFeature;

package/src/device/basic/createHapticsFeature.js

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import * as Haptics from 'expo-haptics';
+
+const IMPACTS = {
+  light: Haptics.ImpactFeedbackStyle.Light,
+  medium: Haptics.ImpactFeedbackStyle.Medium,
+  heavy: Haptics.ImpactFeedbackStyle.Heavy,
+};
+const NOTIFICATIONS = {
+  success: Haptics.NotificationFeedbackType.Success,
+  warning: Haptics.NotificationFeedbackType.Warning,
+  error: Haptics.NotificationFeedbackType.Error,
+};
+
+/**
+ * The haptics device feature: `(type) => Promise`, a selection tick, an impact or a notification
+ * (blocks-native's Haptic action and the native controls' feedback).
+ */
+function createHapticsFeature() {
+  return function playHaptic(hapticType) {
+    if (hapticType === 'selection') {
+      return Haptics.selectionAsync();
+    }
+    if (NOTIFICATIONS[hapticType] !== undefined) {
+      return Haptics.notificationAsync(NOTIFICATIONS[hapticType]);
+    }
+    return Haptics.impactAsync(IMPACTS[hapticType] ?? IMPACTS.light);
+  };
+}
+
+export default createHapticsFeature;

package/src/device/basic/createKeepAwakeFeature.js

@@ -0,0 +1,37 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { activateKeepAwakeAsync, deactivateKeepAwake } from 'expo-keep-awake';
+
+const TAG = 'lowdefy-keep-awake';
+
+/**
+ * The keepAwake device feature (KeepAwake): keeps the screen on, or lets it sleep again. The shell
+ * lets it sleep when the app goes to the background.
+ */
+function createKeepAwakeFeature() {
+  return {
+    async set({ on = true }) {
+      if (on) {
+        await activateKeepAwakeAsync(TAG);
+        return;
+      }
+      deactivateKeepAwake(TAG);
+    },
+  };
+}
+
+export default createKeepAwakeFeature;

package/src/device/basic/createPhotosFeature.js

@@ -0,0 +1,40 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import * as ImagePicker from 'expo-image-picker';
+
+import toImagePickerOptions from './toImagePickerOptions.js';
+import toPickedFile from './toPickedFile.js';
+
+/**
+ * The photos device feature: picks photos and videos with the system picker, which needs no
+ * permission (PHPicker on iOS, the Photo Picker on Android). [] when cancelled.
+ */
+function createPhotosFeature() {
+  return {
+    async pick(params) {
+      const result = await ImagePicker.launchImageLibraryAsync(toImagePickerOptions(params));
+      if (result.canceled) {
+        return [];
+      }
+      return Promise.all(
+        result.assets.map((asset) => toPickedFile({ asset, base64: params.base64 === true }))
+      );
+    },
+  };
+}
+
+export default createPhotosFeature;

package/src/device/basic/createRequestQueueFeature.js

@@ -0,0 +1,37 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { getCurrentApp } from '../../native/currentApp.js';
+
+/**
+ * The requestQueue device feature (GetRequestQueue, RetryRequestQueue, DiscardQueuedRequest): the
+ * open app's offline request queue (src/queue/createRequestQueue.js).
+ */
+function createRequestQueueFeature() {
+  return {
+    async get() {
+      return (await getCurrentApp()).requestQueue.get();
+    },
+    async retry(params) {
+      return (await getCurrentApp()).requestQueue.retry(params);
+    },
+    async discard(params) {
+      return (await getCurrentApp()).requestQueue.discard(params);
+    },
+  };
+}
+
+export default createRequestQueueFeature;

package/src/device/basic/createShareFeature.js

@@ -0,0 +1,63 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { Share } from 'react-native';
+import { File, Paths } from 'expo-file-system';
+import * as Sharing from 'expo-sharing';
+import { type } from '@lowdefy/helpers';
+
+// The last segment of a name from page data, so "../" cannot write outside the cache.
+function toFileName(name) {
+  const base = String(name ?? '')
+    .split(/[\\/]/)
+    .pop();
+  return base === '' || base === '.' || base === '..' ? 'shared-file' : base;
+}
+
+// The file to share: a file on the phone as it is, an https file downloaded to the cache first, or
+// base64 content written to the cache under its name.
+async function toLocalFile({ base64, name, uri }) {
+  if (type.isString(base64)) {
+    const file = new File(Paths.cache, toFileName(name));
+    if (file.exists) file.delete();
+    file.create();
+    file.write(base64, { encoding: 'base64' });
+    return file.uri;
+  }
+  if (/^https?:\/\//.test(uri)) {
+    const file = await File.downloadFileAsync(uri, Paths.cache, { idempotent: true });
+    return file.uri;
+  }
+  return uri;
+}
+
+/**
+ * The share device feature: the system share sheet with text or a link (React Native's Share), or
+ * a file (expo-sharing). Returns { shared }; iOS tells a dismissed sheet apart, Android does not.
+ */
+function createShareFeature() {
+  return async function share({ base64, mimeType, name, text, title, uri, url }) {
+    if (type.isString(uri) || type.isString(base64)) {
+      const local = await toLocalFile({ base64, name, uri });
+      await Sharing.shareAsync(local, { dialogTitle: title, mimeType });
+      return { shared: true };
+    }
+    const result = await Share.share({ message: text ?? url, title, url });
+    return { shared: result.action !== Share.dismissedAction };
+  };
+}
+
+export default createShareFeature;

package/src/device/basic/createShareFeature.test.js

@@ -0,0 +1,47 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import createShareFeature from './createShareFeature.js';
+
+// expo-file-system and expo-sharing both map to the native stand-in (jest.config.js), so one mock
+// serves both.
+jest.mock('expo-file-system', () => ({
+  Paths: { cache: 'file:///cache' },
+  File: class {
+    constructor(directory, name) {
+      this.uri = `${directory}/${name}`;
+      this.exists = false;
+    }
+    create() {}
+    write() {}
+  },
+  shareAsync: jest.fn(async () => undefined),
+}));
+
+const Sharing = require('expo-sharing');
+
+async function shareNamed(name) {
+  await createShareFeature()({ base64: 'aGk=', name });
+  return Sharing.shareAsync.mock.calls.at(-1)[0];
+}
+
+test('a shared base64 file is written to the cache under the last segment of its name', async () => {
+  expect(await shareNamed('report.pdf')).toBe('file:///cache/report.pdf');
+  expect(await shareNamed('../../Documents/token.json')).toBe('file:///cache/token.json');
+  expect(await shareNamed('..\\secrets.txt')).toBe('file:///cache/secrets.txt');
+  expect(await shareNamed('..')).toBe('file:///cache/shared-file');
+  expect(await shareNamed(undefined)).toBe('file:///cache/shared-file');
+});

package/src/device/basic/createSpeechFeature.js

@@ -0,0 +1,43 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import * as Speech from 'expo-speech';
+
+/**
+ * The speech device feature (Speak, StopSpeaking): reads text aloud with the phone's voice. speak
+ * resolves when the text is done, stopped or fails.
+ */
+function createSpeechFeature() {
+  return {
+    speak({ language, pitch, rate, text }) {
+      return new Promise((resolve) => {
+        Speech.speak(text, {
+          language,
+          pitch,
+          rate,
+          onDone: () => resolve({ done: true }),
+          onStopped: () => resolve({ done: false }),
+          onError: () => resolve({ done: false }),
+        });
+      });
+    },
+    async stop() {
+      await Speech.stop();
+    },
+  };
+}
+
+export default createSpeechFeature;

package/src/device/basic/createUploadFeature.js

@@ -0,0 +1,41 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { File } from 'expo-file-system';
+
+import callEndpoint from '../../native/callEndpoint.js';
+import { getCurrentApp } from '../../native/currentApp.js';
+
+/**
+ * The upload device feature: sends one picked file to an API endpoint as
+ * { ...payload, file: { name, mimeType, size, base64 } } and returns the endpoint's answer. The
+ * endpoint stores it (S3, a database, the files module) as the app decides.
+ */
+function createUploadFeature() {
+  return async function upload({ endpointId, file, payload }) {
+    const base64 = file.base64 ?? (await new File(file.uri).base64());
+    return callEndpoint({
+      app: await getCurrentApp(),
+      endpointId,
+      payload: {
+        ...payload,
+        file: { base64, mimeType: file.mimeType, name: file.name, size: file.size },
+      },
+    });
+  };
+}
+
+export default createUploadFeature;

package/src/device/basic/toImagePickerOptions.js

@@ -0,0 +1,41 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+const MEDIA_TYPES = { images: 'images', videos: 'videos' };
+
+/**
+ * PickImage and TakePhoto params as expo-image-picker options. Videos come back as files; photos
+ * are compressed to `quality`.
+ *
+ * @param {Object} params
+ */
+function toImagePickerOptions({
+  maxCount,
+  mediaTypes = ['images'],
+  multiple = false,
+  quality = 0.7,
+}) {
+  return {
+    allowsMultipleSelection: multiple,
+    base64: false,
+    exif: false,
+    mediaTypes: mediaTypes.map((mediaType) => MEDIA_TYPES[mediaType]),
+    quality,
+    selectionLimit: multiple ? maxCount ?? 0 : 1,
+  };
+}
+
+export default toImagePickerOptions;

package/src/device/basic/toPickedFile.js

@@ -0,0 +1,54 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { File } from 'expo-file-system';
+
+// A file name for a picked asset that has none (a camera photo on Android): its kind and the time.
+function fallbackName({ mimeType }) {
+  const extension = (mimeType ?? 'application/octet-stream').split('/')[1] ?? 'bin';
+  return `file-${Date.now()}.${extension}`;
+}
+
+/**
+ * A picked image, video or document as the native actions return it:
+ * { name, mimeType, size, uri, width?, height?, duration?, base64? }.
+ *
+ * @param {Object} params
+ * @param {Object} params.asset An expo-image-picker or expo-document-picker asset.
+ * @param {boolean} [params.base64] Read the content as base64 too.
+ */
+async function toPickedFile({ asset, base64 = false }) {
+  const mimeType = asset.mimeType ?? null;
+  const file = {
+    name: asset.fileName ?? asset.name ?? fallbackName({ mimeType }),
+    mimeType,
+    size: asset.fileSize ?? asset.size ?? new File(asset.uri).size ?? null,
+    uri: asset.uri,
+  };
+  if (typeof asset.width === 'number') {
+    file.width = asset.width;
+    file.height = asset.height;
+  }
+  if (typeof asset.duration === 'number') {
+    file.duration = asset.duration;
+  }
+  if (base64) {
+    file.base64 = asset.base64 ?? (await new File(asset.uri).base64());
+  }
+  return file;
+}
+
+export default toPickedFile;