@lowdefy/shell 3.23.2 → 7.2.0

package/src/device/calendar/index.js

@@ -0,0 +1,68 @@
+/*
+  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 { getCalendars, listEvents, requestCalendarPermissions } from 'expo-calendar';
+import { createEventInCalendarAsync } from 'expo-calendar/legacy';
+import { UserError } from '@lowdefy/errors';
+
+const HOUR = 60 * 60 * 1000;
+
+/**
+ * The calendar device feature (the calendar extension): AddCalendarEvent opens the system event
+ * editor filled in, for the person to save; GetCalendarEvents reads events between two dates from
+ * every calendar, after asking for calendar access.
+ */
+const calendar = {
+  async add({ allDay, end, location, notes, start, title, url }) {
+    const startDate = new Date(start);
+    // The system editor needs no calendar permission; SDK 58 keeps it under expo-calendar/legacy.
+    const result = await createEventInCalendarAsync({
+      allDay: allDay === true,
+      endDate: end ? new Date(end) : new Date(startDate.getTime() + HOUR),
+      location,
+      notes,
+      startDate,
+      title,
+      url,
+    });
+    return result.action === 'saved' || result.action === 'done' ? { id: result.id ?? null } : null;
+  },
+  async getEvents({ end, start }) {
+    const { granted } = await requestCalendarPermissions();
+    if (!granted) {
+      throw new UserError('Calendar permission was denied.');
+    }
+    const calendars = await getCalendars();
+    const byId = Object.fromEntries(calendars.map((item) => [item.id, item.title]));
+    const events = await listEvents(calendars, new Date(start), new Date(end));
+    return events.map((event) => ({
+      id: event.id,
+      title: event.title,
+      start: new Date(event.startDate).toISOString(),
+      end: new Date(event.endDate).toISOString(),
+      allDay: event.allDay === true,
+      location: event.location ?? null,
+      notes: event.notes ?? null,
+      calendar: byId[event.calendarId] ?? null,
+    }));
+  },
+};
+
+// The calendar extension's device features (profiles.js CALENDAR_ENTRY).
+const features = { calendar };
+const hosts = [];
+
+export { features, hosts };

package/src/device/contacts/index.js

@@ -0,0 +1,67 @@
+/*
+  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 { Contact, ContactField } from 'expo-contacts';
+
+const FIELDS = [
+  ContactField.FULL_NAME,
+  ContactField.GIVEN_NAME,
+  ContactField.FAMILY_NAME,
+  ContactField.COMPANY,
+  ContactField.EMAILS,
+  ContactField.PHONES,
+];
+
+async function toContact(contact) {
+  const details = await contact.getDetails(FIELDS);
+  return {
+    id: contact.id,
+    name: details.fullName ?? null,
+    firstName: details.givenName ?? null,
+    lastName: details.familyName ?? null,
+    company: details.company ?? null,
+    emails: (details.emails ?? []).map((entry) => entry.address),
+    phoneNumbers: (details.phones ?? []).map((entry) => entry.number),
+  };
+}
+
+/**
+ * The contacts device feature (the contacts extension): PickContact opens the system contact
+ * picker; AddContact opens the new-contact form filled in for the person to save. Returns
+ * { saved } since the form does not say which contact it made.
+ */
+const contacts = {
+  async pick() {
+    const contact = await Contact.presentPicker();
+    return contact === null ? null : toContact(contact);
+  },
+  async add({ company, emails = [], firstName, lastName, phoneNumbers = [] }) {
+    const saved = await Contact.presentCreateForm({
+      company,
+      emails: emails.map((address) => ({ address, label: 'work' })),
+      familyName: lastName,
+      givenName: firstName,
+      phones: phoneNumbers.map((number) => ({ number, label: 'mobile' })),
+    });
+    return saved ? { saved: true } : null;
+  },
+};
+
+// The contacts extension's device features (profiles.js CONTACTS_ENTRY).
+const features = { contacts };
+const hosts = [];
+
+export { features, hosts };

package/src/device/createDevice.js

@@ -0,0 +1,65 @@
+/*
+  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 calendarEntry from './calendar/index.js';
+import * as contactsEntry from './contacts/index.js';
+import createFilesFeature from './basic/createFilesFeature.js';
+import createHapticsFeature from './basic/createHapticsFeature.js';
+import createKeepAwakeFeature from './basic/createKeepAwakeFeature.js';
+import createNotificationsFeature from '../notifications/createNotificationsFeature.js';
+import createPhotosFeature from './basic/createPhotosFeature.js';
+import createRequestQueueFeature from './basic/createRequestQueueFeature.js';
+import createShareFeature from './basic/createShareFeature.js';
+import createSpeechFeature from './basic/createSpeechFeature.js';
+import createUploadFeature from './basic/createUploadFeature.js';
+import * as fieldEntry from './field/index.js';
+import * as nfcEntry from './nfc/index.js';
+import * as trackingEntry from './tracking/index.js';
+import * as widgetsEntry from '../widgets/index.js';
+
+// The feature modules of profiles and extensions (profiles.js jsEntries). A shell that does not
+// carry one resolves it to an empty module (metro.config.js), which has no `features`.
+const ENTRIES = [fieldEntry, nfcEntry, trackingEntry, contactsEntry, calendarEntry, widgetsEntry];
+
+/**
+ * The device features this shell carries, for blocks-native's device registry (installDevice): the
+ * ones every shell has, and those of the profile and extensions it was built with. `hosts` are the
+ * views features open at the root, such as the ScanCode sheet (DeviceHosts).
+ *
+ * @returns {{ features: Object, hosts: Function[] }}
+ */
+function createDevice() {
+  const carried = ENTRIES.filter((entry) => entry.features !== undefined);
+  return {
+    features: Object.assign(
+      {
+        files: createFilesFeature(),
+        haptics: createHapticsFeature(),
+        keepAwake: createKeepAwakeFeature(),
+        notifications: createNotificationsFeature(),
+        photos: createPhotosFeature(),
+        requestQueue: createRequestQueueFeature(),
+        share: createShareFeature(),
+        speech: createSpeechFeature(),
+        upload: createUploadFeature(),
+      },
+      ...carried.map((entry) => entry.features)
+    ),
+    hosts: carried.flatMap((entry) => entry.hosts),
+  };
+}
+
+export default createDevice;

package/src/device/device.js

@@ -0,0 +1,27 @@
+/*
+  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 { installDevice } from '@lowdefy/blocks-native/device';
+
+import createDevice from './createDevice.js';
+
+// The shell's one device: built and installed when the bundle loads, before any page runs an
+// action, so background tasks launched with no screen find it too. Lowdefy Dev installs a wrapped
+// copy that answers injected results first (src/dev/inject/withInjectedDevice.js).
+const device = createDevice();
+installDevice(device.features);
+
+export default device;

package/src/device/field/MapView.js

@@ -0,0 +1,93 @@
+/*
+  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 { Platform } from 'react-native';
+import { AppleMaps, GoogleMaps } from 'expo-maps';
+
+const APPLE_MAP_TYPES = { standard: 'STANDARD', satellite: 'IMAGERY', hybrid: 'HYBRID' };
+const GOOGLE_MAP_TYPES = { standard: 'NORMAL', satellite: 'SATELLITE', hybrid: 'HYBRID' };
+
+function toCoordinates({ latitude, longitude }) {
+  return { latitude, longitude };
+}
+
+/**
+ * The map the Map block draws (profile field): Apple Maps on iOS, Google Maps on Android
+ * (expo-maps), from the block's markers, lines and camera. Taps and camera moves come back in the
+ * block's terms.
+ */
+function MapView({
+  center,
+  mapType,
+  markerColor,
+  markers,
+  onMapClick,
+  onMarkerClick,
+  onRegionChange,
+  polylines,
+  showsUserLocation,
+  style,
+  zoom,
+}) {
+  const cameraPosition = center === null ? undefined : { coordinates: toCoordinates(center), zoom };
+  const mapMarkers = markers.map((marker, index) => ({
+    id: marker.id ?? String(index),
+    coordinates: toCoordinates(marker),
+    title: marker.title,
+    snippet: marker.description,
+    tintColor: marker.color ?? markerColor,
+  }));
+  const lines = polylines.map((line, index) => ({
+    id: line.id ?? String(index),
+    coordinates: line.coordinates.map(toCoordinates),
+    color: line.color ?? markerColor,
+    width: line.width ?? 4,
+  }));
+  const events = {
+    onMapClick: ({ coordinates }) => onMapClick(coordinates),
+    onMarkerClick: (clicked) => {
+      const index = mapMarkers.findIndex((marker) => marker.id === clicked.id);
+      onMarkerClick(markers[index] ?? clicked);
+    },
+    onCameraMove: ({ coordinates, zoom: nextZoom }) =>
+      onRegionChange({ center: coordinates, zoom: nextZoom }),
+  };
+  if (Platform.OS === 'ios') {
+    return (
+      <AppleMaps.View
+        cameraPosition={cameraPosition}
+        markers={mapMarkers}
+        polylines={lines}
+        properties={{ isMyLocationEnabled: showsUserLocation, mapType: APPLE_MAP_TYPES[mapType] }}
+        style={style}
+        {...events}
+      />
+    );
+  }
+  return (
+    <GoogleMaps.View
+      cameraPosition={cameraPosition}
+      markers={mapMarkers}
+      polylines={lines}
+      properties={{ isMyLocationEnabled: showsUserLocation, mapType: GOOGLE_MAP_TYPES[mapType] }}
+      style={style}
+      {...events}
+    />
+  );
+}
+
+export default MapView;

package/src/device/field/ScanCodeSheet.js

@@ -0,0 +1,86 @@
+/*
+  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, { useEffect, useState } from 'react';
+import { Modal, Pressable, Text, View } from 'react-native';
+
+import ScannerView from './ScannerView.js';
+import scanRequests from './scanRequests.js';
+
+// The full-screen camera the ScanCode action opens: the first code read answers it; Cancel answers
+// null. Mounted once at the root (DeviceHosts).
+function ScanCodeSheet() {
+  const [request, setRequest] = useState(scanRequests.get());
+  const [torch, setTorch] = useState(false);
+  useEffect(() => scanRequests.subscribe(setRequest), []);
+  useEffect(() => setTorch(request?.params.torch === true), [request]);
+  if (request === null) {
+    return null;
+  }
+  return (
+    <Modal
+      animationType="slide"
+      onRequestClose={() => scanRequests.finish(null)}
+      presentationStyle="fullScreen"
+      visible
+    >
+      <View style={{ backgroundColor: '#000000', flex: 1 }}>
+        <ScannerView
+          onScan={(read) => scanRequests.finish(read)}
+          style={{ flex: 1 }}
+          torch={torch}
+          types={request.params.types}
+        />
+        {request.params.prompt ? (
+          <Text
+            style={{
+              color: '#FFFFFF',
+              fontSize: 17,
+              left: 24,
+              position: 'absolute',
+              right: 24,
+              textAlign: 'center',
+              top: 80,
+            }}
+          >
+            {request.params.prompt}
+          </Text>
+        ) : null}
+        <View
+          style={{
+            bottom: 48,
+            flexDirection: 'row',
+            justifyContent: 'space-between',
+            left: 24,
+            position: 'absolute',
+            right: 24,
+          }}
+        >
+          <Pressable accessibilityRole="button" onPress={() => scanRequests.finish(null)}>
+            <Text style={{ color: '#FFFFFF', fontSize: 17 }}>Cancel</Text>
+          </Pressable>
+          <Pressable accessibilityRole="button" onPress={() => setTorch((on) => !on)}>
+            <Text style={{ color: '#FFFFFF', fontSize: 17 }}>
+              {torch ? 'Torch off' : 'Torch on'}
+            </Text>
+          </Pressable>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+export default ScanCodeSheet;

package/src/device/field/ScannerView.js

@@ -0,0 +1,52 @@
+/*
+  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 { CameraView } from 'expo-camera';
+
+const ALL_TYPES = [
+  'qr',
+  'ean13',
+  'ean8',
+  'code128',
+  'code39',
+  'code93',
+  'upc_a',
+  'upc_e',
+  'pdf417',
+  'datamatrix',
+  'aztec',
+  'itf14',
+  'codabar',
+];
+
+/**
+ * The live code scanner the QRScanner block and the ScanCode sheet draw: expo-camera's camera with
+ * barcode scanning (DataScanner on iOS, ML Kit on Android). Each read calls onScan({ data, type }).
+ */
+function ScannerView({ onScan, style, torch, types }) {
+  return (
+    <CameraView
+      barcodeScannerSettings={{ barcodeTypes: types ?? ALL_TYPES }}
+      enableTorch={torch === true}
+      facing="back"
+      onBarcodeScanned={({ data, type }) => onScan({ data, type })}
+      style={style}
+    />
+  );
+}
+
+export default ScannerView;

package/src/device/field/createAudioFeature.js

@@ -0,0 +1,70 @@
+/*
+  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 {
+  AudioModule,
+  RecordingPresets,
+  requestRecordingPermissionsAsync,
+  setAudioModeAsync,
+} from 'expo-audio';
+import { UserError } from '@lowdefy/errors';
+
+import toPickedFile from '../basic/toPickedFile.js';
+
+/**
+ * The audio device feature (profile field): one voice note at a time (StartRecording,
+ * StopRecording). Stop returns the recording as a file with its duration, or null when nothing was
+ * recording.
+ */
+function createAudioFeature() {
+  let recorder = null;
+  let startedAt = null;
+  return {
+    async start({ quality = 'high' } = {}) {
+      const { granted } = await requestRecordingPermissionsAsync();
+      if (!granted) {
+        throw new UserError('Microphone permission was denied.');
+      }
+      if (recorder !== null) {
+        await recorder.stop();
+      }
+      await setAudioModeAsync({ allowsRecording: true, playsInSilentMode: true });
+      recorder = new AudioModule.AudioRecorder(
+        quality === 'low' ? RecordingPresets.LOW_QUALITY : RecordingPresets.HIGH_QUALITY
+      );
+      await recorder.prepareToRecordAsync();
+      recorder.record();
+      startedAt = Date.now();
+      return { recording: true };
+    },
+    async stop({ base64 = false } = {}) {
+      if (recorder === null) {
+        return null;
+      }
+      const current = recorder;
+      recorder = null;
+      await current.stop();
+      await setAudioModeAsync({ allowsRecording: false });
+      const file = await toPickedFile({
+        asset: { mimeType: 'audio/mp4', name: `voice-note-${startedAt}.m4a`, uri: current.uri },
+        base64,
+      });
+      return { ...file, duration: (Date.now() - startedAt) / 1000 };
+    },
+  };
+}
+
+export default createAudioFeature;

package/src/device/field/createBrightnessFeature.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 Brightness from 'expo-brightness';
+import { type } from '@lowdefy/helpers';
+
+/**
+ * The brightness device feature (profile field): SetBrightness sets the app's screen brightness,
+ * for a scan screen, and gives it back to the system with `reset`. The app's brightness ends when it
+ * goes to the background.
+ */
+function createBrightnessFeature() {
+  return {
+    async set({ level, reset }) {
+      if (reset === true) {
+        await Brightness.restoreSystemBrightnessAsync();
+        return;
+      }
+      if (!type.isNumber(level)) {
+        throw new Error('SetBrightness requires "level" from 0 to 1, or "reset: true".');
+      }
+      await Brightness.setBrightnessAsync(Math.min(1, Math.max(0, level)));
+    },
+  };
+}
+
+export default createBrightnessFeature;

package/src/device/field/createCameraFeature.js

@@ -0,0 +1,56 @@
+/*
+  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 { Camera } from 'expo-camera';
+import * as ImagePicker from 'expo-image-picker';
+import { UserError } from '@lowdefy/errors';
+
+import scanRequests from './scanRequests.js';
+import ScannerView from './ScannerView.js';
+import toImagePickerOptions from '../basic/toImagePickerOptions.js';
+import toPickedFile from '../basic/toPickedFile.js';
+
+/**
+ * The camera device feature (profile field): ScanCode's sheet, TakePhoto's capture and the live
+ * ScannerView the QRScanner block draws. Each asks for the camera the first time; a refusal throws.
+ */
+function createCameraFeature() {
+  async function allowCamera() {
+    const { granted } = await Camera.requestCameraPermissionsAsync();
+    if (!granted) {
+      throw new UserError('Camera permission was denied.');
+    }
+  }
+  return {
+    ScannerView,
+    async scanCode(params) {
+      await allowCamera();
+      return scanRequests.open(params);
+    },
+    async takePhoto(params) {
+      await allowCamera();
+      const result = await ImagePicker.launchCameraAsync(toImagePickerOptions(params));
+      if (result.canceled) {
+        return [];
+      }
+      return Promise.all(
+        result.assets.map((asset) => toPickedFile({ asset, base64: params.base64 === true }))
+      );
+    },
+  };
+}
+
+export default createCameraFeature;

package/src/device/field/createDocumentScannerFeature.js

@@ -0,0 +1,51 @@
+/*
+  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 DocumentScanner, { ResponseType } from 'react-native-document-scanner-plugin';
+
+import toPickedFile from '../basic/toPickedFile.js';
+
+/**
+ * The documentScanner device feature (profile field): the system document scanner (VisionKit on
+ * iOS, ML Kit on Android) finds each page's edges, crops and straightens it. Pages come back as
+ * JPEG files; [] when cancelled.
+ */
+function createDocumentScannerFeature() {
+  return async function scanDocument({ base64 = false, maxPages, quality = 0.8 }) {
+    const { scannedImages, status } = await DocumentScanner.scanDocument({
+      croppedImageQuality: Math.round(quality * 100),
+      maxNumDocuments: maxPages,
+      responseType: ResponseType.ImageFilePath,
+    });
+    if (status === 'cancel' || !Array.isArray(scannedImages)) {
+      return [];
+    }
+    return Promise.all(
+      scannedImages.map((uri, index) =>
+        toPickedFile({
+          asset: {
+            mimeType: 'image/jpeg',
+            name: `scan-${Date.now()}-${index + 1}.jpg`,
+            uri: uri.startsWith('file://') ? uri : `file://${uri}`,
+          },
+          base64,
+        })
+      )
+    );
+  };
+}
+
+export default createDocumentScannerFeature;