@lowdefy/shell 0.0.0-experimental-20261019052246

package/src/actions/ScrollTo.test.js

@@ -0,0 +1,83 @@
+/*
+  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 ScrollTo from './ScrollTo.js';
+
+const methods = { getPageId: () => 'home' };
+
+// A ScrollView 600 high, and a block view 100 high at 1000 in its content.
+function createPage({ withView = true } = {}) {
+  const innerView = { name: 'content' };
+  const scrollView = {
+    getInnerViewRef: () => innerView,
+    getNativeScrollRef: () => ({ measure: (callback) => callback(0, 0, 400, 600) }),
+    scrollTo: jest.fn(),
+  };
+  const view = {
+    measureLayout: jest.fn((relativeTo, onSuccess) => onSuccess(0, 1000, 400, 100)),
+  };
+  const registered = {
+    'scroll:home:': scrollView,
+    ...(withView ? { 'view:home:jobs': view } : {}),
+  };
+  const globals = {
+    elements: {
+      find: ({ blockId, kind, pageId }) => registered[`${kind}:${pageId}:${blockId ?? ''}`] ?? null,
+    },
+  };
+  return { globals, innerView, scrollView, view };
+}
+
+test('ScrollTo throws without params', async () => {
+  await expect(ScrollTo({ globals: createPage().globals, methods })).rejects.toThrow(
+    'Invalid ScrollTo, check action params.'
+  );
+});
+
+test('ScrollTo without a blockId scrolls the page to top, as window.scrollTo does', async () => {
+  const { globals, scrollView } = createPage();
+  await ScrollTo({ globals, methods, params: { top: 200, behavior: 'smooth' } });
+  expect(scrollView.scrollTo.mock.calls).toEqual([[{ animated: true, x: 0, y: 200 }]]);
+});
+
+test('ScrollTo scrolls a block to the top of the page, measured in the scroll content', async () => {
+  const { globals, innerView, scrollView, view } = createPage();
+  await ScrollTo({ globals, methods, params: { blockId: 'jobs' } });
+  expect(view.measureLayout.mock.calls[0][0]).toBe(innerView);
+  expect(scrollView.scrollTo.mock.calls).toEqual([[{ animated: false, x: 0, y: 1000 }]]);
+});
+
+test('ScrollTo places a block at the center or end of the page by options.block', async () => {
+  const { globals, scrollView } = createPage();
+  await ScrollTo({
+    globals,
+    methods,
+    params: { blockId: 'jobs', options: { block: 'center', behavior: 'smooth' } },
+  });
+  await ScrollTo({ globals, methods, params: { blockId: 'jobs', options: { block: 'end' } } });
+  expect(scrollView.scrollTo.mock.calls).toEqual([
+    [{ animated: true, x: 0, y: 750 }],
+    [{ animated: false, x: 0, y: 500 }],
+  ]);
+});
+
+test('ScrollTo leaves the page where it is for a block not on it', async () => {
+  const { globals, scrollView } = createPage({ withView: false });
+  await ScrollTo({ globals, methods, params: { blockId: 'jobs' } });
+  expect(scrollView.scrollTo).not.toHaveBeenCalled();
+});

package/src/actions/SetFocus.js

@@ -0,0 +1,33 @@
+/*
+  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 { type } from '@lowdefy/helpers';
+
+// The native body of actions-core's SetFocus: focuses the control the block registered as its
+// input (useElementRef kind 'input'). As on the web, a block with nothing to focus is left alone.
+function SetFocus({ globals, methods, params }) {
+  if (!type.isString(params)) {
+    throw new Error('SetFocus parameter must be a string.');
+  }
+  const input = globals.elements.find({
+    blockId: params,
+    kind: 'input',
+    pageId: methods.getPageId(),
+  });
+  input?.focus?.();
+}
+
+export default SetFocus;

package/src/actions/SetFocus.test.js

@@ -0,0 +1,49 @@
+/*
+  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 SetFocus from './SetFocus.js';
+
+function createGlobals(elements) {
+  return {
+    elements: {
+      find: ({ blockId, kind, pageId }) => elements[`${kind}:${pageId}:${blockId}`] ?? null,
+    },
+  };
+}
+
+const methods = { getPageId: () => 'home' };
+
+test('SetFocus focuses the input the block registered on the page', () => {
+  const input = { focus: jest.fn() };
+  SetFocus({ globals: createGlobals({ 'input:home:name': input }), methods, params: 'name' });
+  expect(input.focus).toHaveBeenCalledTimes(1);
+});
+
+test('SetFocus leaves a block with nothing to focus alone', () => {
+  const other = { focus: jest.fn() };
+  expect(() =>
+    SetFocus({ globals: createGlobals({ 'input:other:name': other }), methods, params: 'name' })
+  ).not.toThrow();
+  expect(other.focus).not.toHaveBeenCalled();
+});
+
+test('SetFocus takes a block id string', () => {
+  expect(() => SetFocus({ globals: createGlobals({}), methods, params: { blockId: 'a' } })).toThrow(
+    'SetFocus parameter must be a string.'
+  );
+});

package/src/actions/SetLocalStorage.js

@@ -0,0 +1,34 @@
+/*
+  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 { serializer, type } from '@lowdefy/helpers';
+import validateStorageKey from '@lowdefy/actions-core/localStorage/validateStorageKey.js';
+
+// The native body of actions-core's SetLocalStorage: writes the app's key to the device store
+// (expo-sqlite's key-value store), where the web writes localStorage.
+function SetLocalStorage({ globals, methods, params }) {
+  if (!type.isObject(params)) {
+    throw new Error('SetLocalStorage params should be an object.');
+  }
+  const { key, value } = params;
+  validateStorageKey({ actionType: 'SetLocalStorage', key });
+  if (type.isUndefined(value)) {
+    throw new Error('SetLocalStorage "value" is required.');
+  }
+  globals.storage.set(methods.getAppStorageKey(key), serializer.serializeToString(value));
+}
+
+export default SetLocalStorage;

package/src/actions/localStorage.test.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 createMemoryStore from '../host/createMemoryStore.js';
+import GetLocalStorage from './GetLocalStorage.js';
+import RemoveLocalStorage from './RemoveLocalStorage.js';
+import SetLocalStorage from './SetLocalStorage.js';
+
+const methods = { getAppStorageKey: (key) => `lowdefy:field::${key}` };
+
+function createGlobals() {
+  return { storage: createMemoryStore() };
+}
+
+test('SetLocalStorage keeps a serialized value under the app key, which GetLocalStorage reads', () => {
+  const globals = createGlobals();
+  const value = { due: new Date(1600000000000), title: 'Pump' };
+  SetLocalStorage({ globals, methods, params: { key: 'draft', value } });
+  expect(globals.storage.get('lowdefy:field::draft')).toBe(
+    '{"due":{"~d":1600000000000},"title":"Pump"}'
+  );
+  expect(GetLocalStorage({ globals, methods, params: { key: 'draft' } })).toEqual(value);
+});
+
+test('GetLocalStorage gives the default for a key not set, and a plain string as it is', () => {
+  const globals = createGlobals();
+  expect(GetLocalStorage({ globals, methods, params: { key: 'draft', default: 'none' } })).toBe(
+    'none'
+  );
+  globals.storage.set('lowdefy:field::mode', 'dark');
+  expect(GetLocalStorage({ globals, methods, params: { key: 'mode' } })).toBe('dark');
+});
+
+test('RemoveLocalStorage removes the app key', () => {
+  const globals = createGlobals();
+  SetLocalStorage({ globals, methods, params: { key: 'draft', value: 1 } });
+  RemoveLocalStorage({ globals, methods, params: { key: 'draft' } });
+  expect(globals.storage.keys()).toEqual([]);
+});
+
+test('the local storage actions refuse keys Lowdefy keeps for itself', () => {
+  const globals = createGlobals();
+  expect(() =>
+    SetLocalStorage({ globals, methods, params: { key: 'lowdefy_darkMode', value: 'dark' } })
+  ).toThrow('SetLocalStorage "key" "lowdefy_darkMode" is reserved.');
+  expect(() => GetLocalStorage({ globals, methods, params: { key: '' } })).toThrow(
+    'GetLocalStorage "key" should be a non-empty string.'
+  );
+  expect(() => RemoveLocalStorage({ globals, methods, params: 'draft' })).toThrow(
+    'RemoveLocalStorage params should be an object.'
+  );
+  expect(() => SetLocalStorage({ globals, methods, params: { key: 'draft' } })).toThrow(
+    'SetLocalStorage "value" is required.'
+  );
+});

package/src/actions/measureInScrollView.js

@@ -0,0 +1,36 @@
+/*
+  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.
+*/
+
+// The view's position and height in the ScrollView's content, and the height of the ScrollView's
+// visible area.
+function measureInScrollView({ scrollView, view }) {
+  const measureElement = new Promise((resolve, reject) => {
+    view.measureLayout(
+      scrollView.getInnerViewRef(),
+      (left, top, width, height) => resolve({ height, top }),
+      () => reject(new Error('ScrollTo could not measure the block in the page.'))
+    );
+  });
+  const measureViewport = new Promise((resolve) => {
+    scrollView.getNativeScrollRef().measure((x, y, width, height) => resolve({ height }));
+  });
+  return Promise.all([measureElement, measureViewport]).then(([element, viewport]) => ({
+    element,
+    viewport,
+  }));
+}
+
+export default measureInScrollView;

package/src/actions/nativeActions.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 CopyToClipboard from './CopyToClipboard.js';
+import GeolocationCurrentPosition from './GeolocationCurrentPosition.js';
+import GetLocalStorage from './GetLocalStorage.js';
+import RemoveLocalStorage from './RemoveLocalStorage.js';
+import ScrollTo from './ScrollTo.js';
+import SetFocus from './SetFocus.js';
+import SetLocalStorage from './SetLocalStorage.js';
+
+// Native bodies of the actions-core actions whose web bodies reach the DOM, under the same names,
+// so pages call them as on the web. They reach the device through the shell's host globals
+// (createShellGlobals). SetDarkMode and SetLocale keep their actions-core bodies: they call the
+// window members the shell sets (client-native's ThemeProvider and the shell's locale).
+// GeolocationCurrentPosition answers with a location Lowdefy Dev injected until the shell carries
+// device location.
+const nativeActions = {
+  CopyToClipboard,
+  GeolocationCurrentPosition,
+  GetLocalStorage,
+  RemoveLocalStorage,
+  ScrollTo,
+  SetFocus,
+  SetLocalStorage,
+};
+
+export default nativeActions;

package/src/auth/AuthButton.js

@@ -0,0 +1,44 @@
+/*
+  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 { Pressable, Text } from 'react-native';
+
+import styles from './styles.js';
+import useSurfaceTokens from '../components/useSurfaceTokens.js';
+
+function AuthButton({ disabled = false, onPress, testID, title }) {
+  const tokens = useSurfaceTokens();
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityState={{ disabled }}
+      disabled={disabled}
+      onPress={onPress}
+      style={({ pressed }) => [
+        styles.button,
+        { backgroundColor: tokens.colorTint },
+        pressed ? { opacity: 0.7 } : null,
+        disabled ? styles.buttonDisabled : null,
+      ]}
+      testID={testID}
+    >
+      <Text style={styles.buttonText}>{title}</Text>
+    </Pressable>
+  );
+}
+
+export default AuthButton;

package/src/auth/AuthGate.js

@@ -0,0 +1,57 @@
+/*
+  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, useSyncExternalStore } from 'react';
+import * as SplashScreen from 'expo-splash-screen';
+
+import getAuthSettings from './getAuthSettings.js';
+import getAuthView from './getAuthView.js';
+import LoadingScreen from '../components/LoadingScreen.js';
+import LockScreen from './LockScreen.js';
+import SignInScreen from './SignInScreen.js';
+import { useSessionState, useShell } from '../ShellContext.js';
+
+// The lock screen or sign-in screen in place of the app, until it is unlocked and someone is
+// signed in (getAuthView).
+function AuthGate({ children }) {
+  const { auth } = useShell();
+  const authState = useSyncExternalStore(auth.subscribe, auth.getState);
+  const sessionState = useSessionState();
+  const view = getAuthView({ auth: authState, session: sessionState });
+
+  useEffect(() => {
+    if (view === 'lock' || view === 'signIn') SplashScreen.hideAsync();
+  }, [view]);
+
+  if (view === 'lock') {
+    return <LockScreen appName={auth.getAppName()} auth={auth} />;
+  }
+  if (view === 'loading') {
+    return <LoadingScreen />;
+  }
+  if (view === 'signIn') {
+    return (
+      <SignInScreen
+        appName={auth.getAppName()}
+        auth={auth}
+        settings={getAuthSettings(sessionState.root)}
+      />
+    );
+  }
+  return children;
+}
+
+export default AuthGate;

package/src/auth/AuthLink.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 React from 'react';
+import { Pressable, Text } from 'react-native';
+
+import styles from './styles.js';
+import useSurfaceTokens from '../components/useSurfaceTokens.js';
+
+function AuthLink({ disabled = false, onPress, style, testID, title }) {
+  const tokens = useSurfaceTokens();
+  return (
+    <Pressable
+      accessibilityRole="link"
+      accessibilityState={{ disabled }}
+      disabled={disabled}
+      onPress={onPress}
+      style={style}
+      testID={testID}
+    >
+      <Text
+        style={[styles.link, { color: disabled ? tokens.colorTertiaryLabel : tokens.colorTint }]}
+      >
+        {title}
+      </Text>
+    </Pressable>
+  );
+}
+
+export default AuthLink;

package/src/auth/LockScreen.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 React, { useCallback, useEffect, useState } from 'react';
+import { View, Text } from 'react-native';
+
+import AuthButton from './AuthButton.js';
+import AuthLink from './AuthLink.js';
+import styles from './styles.js';
+import useSurfaceTokens from '../components/useSurfaceTokens.js';
+
+/**
+ * The lock screen of an app with biometric unlock: no page shows until Face ID or a fingerprint
+ * unlocks it. It asks at once, and again on Unlock. "Sign in again" signs out, for a person whose
+ * biometrics no longer open the app.
+ */
+function LockScreen({ appName, auth }) {
+  const tokens = useSurfaceTokens();
+  const [busy, setBusy] = useState(false);
+
+  const unlock = useCallback(async () => {
+    setBusy(true);
+    try {
+      await auth.unlock();
+    } finally {
+      setBusy(false);
+    }
+  }, [auth]);
+
+  useEffect(() => {
+    unlock();
+  }, [unlock]);
+
+  return (
+    <View
+      style={[styles.screen, { backgroundColor: tokens.colorGroupedBackground }]}
+      testID="shell-lock"
+    >
+      <Text accessibilityRole="header" style={[styles.appName, { color: tokens.colorLabel }]}>
+        {appName}
+      </Text>
+      <AuthButton disabled={busy} onPress={unlock} testID="lock-unlock" title="Unlock" />
+      <AuthLink
+        disabled={busy}
+        onPress={() => auth.signOut()}
+        style={styles.centered}
+        testID="lock-sign-in-again"
+        title="Sign in again"
+      />
+    </View>
+  );
+}
+
+export default LockScreen;

package/src/auth/LockScreen.test.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 React from 'react';
+import { jest } from '@jest/globals';
+import { fireEvent, render, screen } from '@testing-library/react-native';
+
+import LockScreen from './LockScreen.js';
+
+test('the lock screen asks to unlock at once, and again on Unlock', async () => {
+  const auth = { unlock: jest.fn(async () => false), signOut: jest.fn() };
+  await render(<LockScreen appName="Field" auth={auth} />);
+  expect(screen.getByText('Field')).toBeTruthy();
+  expect(auth.unlock).toHaveBeenCalledTimes(1);
+  await fireEvent.press(screen.getByTestId('lock-unlock'));
+  expect(auth.unlock).toHaveBeenCalledTimes(2);
+});
+
+test('Sign in again signs out', async () => {
+  const auth = { unlock: jest.fn(async () => false), signOut: jest.fn() };
+  await render(<LockScreen appName="Field" auth={auth} />);
+  await fireEvent.press(screen.getByTestId('lock-sign-in-again'));
+  expect(auth.signOut).toHaveBeenCalledTimes(1);
+});