@lowdefy/shell 0.0.0-experimental-20261019052246

package/scripts/createTypeManifest.mjs

@@ -0,0 +1,205 @@
+/*
+  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 type manifest: every block, action and operator type this shell carries, with the plugin
+  package that provides it and that package's major version. A page renders only when the shell
+  carries every type its type set names at the same major version (src/types/checkTypeSet.js).
+
+  Made from src/plugins/shellPlugins.json, the plugin packages the shell registers
+  (src/plugins/types.js), and the shell's plugins (shell.json `plugins`, read with
+  readShellConfig.js): each one's `./types` `native.blocks` and `native.actions`, named with its
+  typePrefix, as src/plugins/appTypes.js registers them. A plugin without a `./types` export adds
+  none. Written to src/plugins/typeManifest.js, which the shell's JavaScript
+  imports (src/config/getShellConfig.js). The manifest travels in the JavaScript bundle, not the
+  Expo config, so it always matches the code that runs: a type added to the plugin maps reaches a
+  shell with an over-the-air update or from Metro, without a native build. The file is committed;
+  src/plugins/types.test.js fails when it is stale, and `pnpm release:version` rewrites it after
+  the version bump. `lowdefy mobile config` rewrites it in a copied shell, with that shell's
+  plugins.
+
+    node scripts/createTypeManifest.mjs           prints the manifest as JSON
+    node scripts/createTypeManifest.mjs --write   writes src/plugins/typeManifest.js
+
+  Usage: pnpm --filter=@lowdefy/shell type-manifest
+*/
+
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const shellRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(import.meta.url);
+const readShellConfig = require('../readShellConfig.js');
+
+const NATIVE_CATEGORIES = ['actions', 'blocks'];
+
+const CATEGORIES = ['actions', 'blocks', 'operators'];
+
+const HEADER = `/*
+  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.
+*/
+
+// Generated by scripts/createTypeManifest.mjs from src/plugins/shellPlugins.json and shell.json
+// \`plugins\`. Do not edit.
+`;
+
+// The plugin packages export no package.json, so it is found above the resolved types file.
+function readMajorVersion(packageName) {
+  let directory = path.dirname(require.resolve(`${packageName}/types`));
+  while (!fs.existsSync(path.join(directory, 'package.json'))) {
+    directory = path.dirname(directory);
+  }
+  const { name, version } = JSON.parse(
+    fs.readFileSync(path.join(directory, 'package.json'), 'utf8')
+  );
+  if (name !== packageName) {
+    throw new Error(`Could not find the package.json of "${packageName}".`);
+  }
+  return Number(version.split('.')[0]);
+}
+
+function getPackageTypeNames({ category, types }) {
+  if (category === 'operators') {
+    return types.operators.client;
+  }
+  return types[category];
+}
+
+// Two packages giving one type name would leave one of them unreachable on a page.
+function addType({ category, manifest, name, packageName }) {
+  const existing = manifest[category][name];
+  if (existing !== undefined && existing.package !== packageName) {
+    throw new Error(
+      `Shell plugin "${packageName}" gives the ${category.slice(0, -1)} type "${name}", which "${
+        existing.package
+      }" already gives. Set a typePrefix on the plugin in mobile.shells[].plugins.`
+    );
+  }
+  manifest[category][name] = { package: packageName, version: readMajorVersion(packageName) };
+}
+
+// A shell plugin need not export "./types": a native-only plugin, such as a wrapped SDK, gives no
+// types. Resolving a missing export throws, so the plugin's own package.json says, found on the
+// lookup paths of `require` (its exports need not list package.json).
+function hasTypesExport(packageName) {
+  const packageJsonPath = require.resolve
+    .paths(packageName)
+    .map((directory) => path.join(directory, packageName, 'package.json'))
+    .find((filePath) => fs.existsSync(filePath));
+  if (packageJsonPath === undefined) {
+    throw new Error(`Shell plugin "${packageName}" is not installed.`);
+  }
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  return packageJson.exports?.['./types'] !== undefined;
+}
+
+// A shell plugin's native type names, from its `./types` `native: { blocks, actions }`.
+async function addShellPluginTypes({ manifest, plugin }) {
+  const { default: types } = await import(pathToFileURL(require.resolve(`${plugin.name}/types`)));
+  NATIVE_CATEGORIES.forEach((category) => {
+    const names = types.native?.[category] ?? [];
+    if (!Array.isArray(names)) {
+      throw new Error(
+        `Shell plugin "${
+          plugin.name
+        }" "./types" native.${category} should be an array of type names. Received ${JSON.stringify(
+          names
+        )}.`
+      );
+    }
+    names.forEach((name) => {
+      addType({
+        category,
+        manifest,
+        name: `${plugin.typePrefix ?? ''}${name}`,
+        packageName: plugin.name,
+      });
+    });
+  });
+}
+
+function readShellPlugins() {
+  return JSON.parse(fs.readFileSync(path.join(shellRoot, 'src/plugins/shellPlugins.json'), 'utf8'));
+}
+
+async function createTypeManifest({
+  plugins = readShellPlugins(),
+  shellPlugins = readShellConfig().shell.plugins ?? [],
+} = {}) {
+  const manifest = { actions: {}, blocks: {}, operators: {} };
+  for (const plugin of plugins) {
+    if (!CATEGORIES.includes(plugin.category)) {
+      throw new Error(
+        `Shell plugin "${plugin.package}" has an unknown category. Received ${JSON.stringify(
+          plugin.category
+        )}.`
+      );
+    }
+    const { default: types } = await import(`${plugin.package}/types`);
+    const packageTypeNames = getPackageTypeNames({ category: plugin.category, types });
+    const names = plugin.types ?? packageTypeNames;
+    names.forEach((name) => {
+      if (!packageTypeNames.includes(name)) {
+        throw new Error(
+          `Shell plugin "${plugin.package}" has no ${plugin.category} type "${name}".`
+        );
+      }
+      addType({ category: plugin.category, manifest, name, packageName: plugin.package });
+    });
+  }
+  for (const plugin of shellPlugins) {
+    if (hasTypesExport(plugin.name)) {
+      await addShellPluginTypes({ manifest, plugin });
+    }
+  }
+  return manifest;
+}
+
+async function createTypeManifestModule() {
+  const manifest = await createTypeManifest();
+  return `${HEADER}\nconst typeManifest = ${JSON.stringify(
+    manifest,
+    null,
+    2
+  )};\n\nexport default typeManifest;\n`;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  if (process.argv.includes('--write')) {
+    fs.writeFileSync(
+      path.join(shellRoot, 'src/plugins/typeManifest.js'),
+      await createTypeManifestModule()
+    );
+  } else {
+    process.stdout.write(JSON.stringify(await createTypeManifest()));
+  }
+}
+
+export default createTypeManifest;

package/shell.dev.json

@@ -0,0 +1,11 @@
+{
+  "id": "lowdefy-dev",
+  "name": "Lowdefy Dev",
+  "profile": "dev",
+  "scheme": "lowdefy-dev",
+  "environment": "dev",
+  "ios": { "bundleIdentifier": "com.lowdefy.dev" },
+  "android": { "package": "com.lowdefy.dev" },
+  "store": {},
+  "app": { "id": "dev", "name": "Lowdefy Dev", "urls": { "dev": "http://localhost:3000" } }
+}

package/shellVariant.js

@@ -0,0 +1,111 @@
+/*
+  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 { DEV_ENTRY, PROFILES, mergeProfiles, pluginName, resolveProfile } = require('./profiles.js');
+
+const VARIANTS = ['dev', 'release'];
+
+// The string the dev-tab client sends to the dev server. scripts/checkReleaseBundle.mjs fails when a
+// release bundle holds it. Keep it in step with src/dev/tab/devClientMarker.js.
+const DEV_CLIENT_MARKER = 'lowdefy-dev-tab-client';
+
+// Everything any profile carries: every module, entry and permission a build can leave out.
+const EVERYTHING = Object.keys(PROFILES).reduce(
+  (all, name) => mergeProfiles(all, resolveProfile(name)),
+  resolveProfile('basic')
+);
+
+// What the `dev` profile adds itself: the developer features, which a release build never carries.
+const DEV_ONLY = PROFILES.dev;
+
+// The shell's capability profile: shell.json `profile`, else `dev` for Lowdefy Dev and `basic` for
+// any other shell.
+function getProfileName({ shell, variant }) {
+  return shell.profile ?? (variant === 'dev' ? 'dev' : 'basic');
+}
+
+/**
+ * What a shell build of this variant carries: its profile, resolved (profiles.js). The dev variant
+ * also carries Lowdefy Dev's developer features, whatever the profile; a release build carries
+ * none of them.
+ */
+function getShellProfile({ shell, variant }) {
+  const profile = resolveProfile(getProfileName({ shell, variant }));
+  if (variant === 'dev') {
+    return mergeProfiles(profile, { ...resolveProfile('dev'), name: profile.name });
+  }
+  return {
+    ...profile,
+    modules: Object.fromEntries(
+      Object.entries(profile.modules).filter(([name]) => !(name in DEV_ONLY.modules))
+    ),
+    plugins: profile.plugins.filter((plugin) => !(pluginName(plugin) in DEV_ONLY.modules)),
+    permissions: profile.permissions.filter(
+      (permission) => !DEV_ONLY.permissions.includes(permission)
+    ),
+    jsEntries: profile.jsEntries.filter((entry) => !DEV_ONLY.jsEntries.includes(entry)),
+  };
+}
+
+/**
+ * What a shell build of this variant leaves out: every module, JavaScript entry and permission some
+ * profile carries and its own does not. app.config.ts leaves the modules unlinked and their config
+ * plugins unapplied (withExcludedNativeModules.js) and blocks the permissions; metro.config.js
+ * resolves the entries to empty modules.
+ *
+ * @returns {{ modules: Object<string, string|null>, jsEntries: string[], permissions: string[] }}
+ *   modules as { [package]: nativeModuleName }.
+ */
+function getExclusions({ shell, variant }) {
+  const profile = getShellProfile({ shell, variant });
+  return {
+    modules: Object.fromEntries(
+      Object.entries(EVERYTHING.modules).filter(([name]) => !(name in profile.modules))
+    ),
+    jsEntries: EVERYTHING.jsEntries.filter((entry) => !profile.jsEntries.includes(entry)),
+    permissions: EVERYTHING.permissions.filter(
+      (permission) => !profile.permissions.includes(permission)
+    ),
+  };
+}
+
+// The native modules a shell build leaves unlinked, as { [package]: nativeModuleName }.
+function getExcludedModules({ shell, variant }) {
+  return getExclusions({ shell, variant }).modules;
+}
+
+// LOWDEFY_SHELL_VARIANT=dev | release. Without it, Lowdefy Dev (no LOWDEFY_SHELL_CONFIG) is dev and
+// every other shell is release, so a customer shell leaves the developer features out unless its
+// build asks for them.
+function getShellVariant(env = process.env) {
+  const variant = env.LOWDEFY_SHELL_VARIANT || (env.LOWDEFY_SHELL_CONFIG ? 'release' : 'dev');
+  if (!VARIANTS.includes(variant)) {
+    throw new Error(
+      `LOWDEFY_SHELL_VARIANT must be "dev" or "release". Received ${JSON.stringify(variant)}.`
+    );
+  }
+  return variant;
+}
+
+module.exports = {
+  DEV_CLIENT_MARKER,
+  DEV_ENTRY,
+  getExcludedModules,
+  getExclusions,
+  getProfileName,
+  getShellProfile,
+  getShellVariant,
+};

package/src/ShellContext.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 { createContext, useContext, useSyncExternalStore } from 'react';
+
+// { auth, session, host, locale, shell } of the app the shell has open.
+const ShellContext = createContext(null);
+
+function useShell() {
+  return useContext(ShellContext);
+}
+
+function useSessionState() {
+  const { session } = useShell();
+  return useSyncExternalStore(session.subscribe, session.getState);
+}
+
+export { useSessionState, useShell };
+export default ShellContext;

package/src/actions/CopyToClipboard.js

@@ -0,0 +1,29 @@
+/*
+  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 CopyToClipboard, with its params ({ copy }), through
+// expo-clipboard (globals.clipboard).
+async function CopyToClipboard({ globals, params }) {
+  const { copy } = params;
+  if (!type.isString(copy)) {
+    throw new Error(`CopyToClipboard requires "copy" text. Received ${JSON.stringify(copy)}.`);
+  }
+  await globals.clipboard.setString(copy);
+}
+
+export default CopyToClipboard;

package/src/actions/CopyToClipboard.test.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 { jest } from '@jest/globals';
+
+import CopyToClipboard from './CopyToClipboard.js';
+
+test('CopyToClipboard copies the text through the shell clipboard', async () => {
+  const clipboard = { setString: jest.fn(async () => undefined) };
+  await CopyToClipboard({ globals: { clipboard }, params: { copy: 'JOB-42' } });
+  expect(clipboard.setString.mock.calls).toEqual([['JOB-42']]);
+});
+
+test('CopyToClipboard throws when there is no text to copy', async () => {
+  const clipboard = { setString: jest.fn(async () => undefined) };
+  await expect(CopyToClipboard({ globals: { clipboard }, params: {} })).rejects.toThrow(
+    'CopyToClipboard requires "copy" text. Received undefined.'
+  );
+  expect(clipboard.setString).not.toHaveBeenCalled();
+});

package/src/actions/GeolocationCurrentPosition.js

@@ -0,0 +1,55 @@
+/*
+  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';
+
+import injected from '../device/injected.js';
+
+function numberOrNull(value) {
+  return type.isNumber(value) ? value : null;
+}
+
+/**
+ * The native body of actions-core's GeolocationCurrentPosition, answering as the web body does:
+ * `{ coords, timestamp }`, or `{ code: 1, error: 'PERMISSION_DENIED', message }` when location is
+ * refused. Until the shell carries device location (the device actions), it answers only with a
+ * location Lowdefy Dev injected (src/device/injected.js), and throws otherwise.
+ */
+async function GeolocationCurrentPosition() {
+  if (injected('permission:location') === 'denied') {
+    return { code: 1, error: 'PERMISSION_DENIED', message: 'Location permission was denied.' };
+  }
+  const location = injected('location');
+  if (type.isUndefined(location)) {
+    throw new Error(
+      'GeolocationCurrentPosition is not available on this phone yet: the shell has no device location. In Lowdefy Dev, inject a location.'
+    );
+  }
+  return {
+    coords: {
+      accuracy: numberOrNull(location.accuracy),
+      altitude: numberOrNull(location.altitude),
+      altitudeAccuracy: numberOrNull(location.altitudeAccuracy),
+      heading: numberOrNull(location.heading),
+      latitude: location.latitude,
+      longitude: location.longitude,
+      speed: numberOrNull(location.speed),
+    },
+    timestamp: location.timestamp ?? Date.now(),
+  };
+}
+
+export default GeolocationCurrentPosition;

package/src/actions/GeolocationCurrentPosition.test.js

@@ -0,0 +1,66 @@
+/*
+  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 createDeviceInjections from '../dev/inject/createDeviceInjections.js';
+import createFakeNetwork from '../test/createFakeNetwork.js';
+import createNetworkStatus from '../host/createNetworkStatus.js';
+import GeolocationCurrentPosition from './GeolocationCurrentPosition.js';
+import { installInjector } from '../device/injected.js';
+
+let injections;
+let remove;
+beforeEach(() => {
+  injections = createDeviceInjections({
+    networkStatus: createNetworkStatus({ network: createFakeNetwork() }),
+  });
+  remove = installInjector(injections);
+});
+afterEach(() => remove());
+
+test('GeolocationCurrentPosition answers with the injected location in the web shape', async () => {
+  injections.inject({
+    kind: 'location',
+    value: { latitude: -33.92, longitude: 18.42, accuracy: 12, timestamp: 1760778000000 },
+  });
+  await expect(GeolocationCurrentPosition({ params: {} })).resolves.toEqual({
+    coords: {
+      accuracy: 12,
+      altitude: null,
+      altitudeAccuracy: null,
+      heading: null,
+      latitude: -33.92,
+      longitude: 18.42,
+      speed: null,
+    },
+    timestamp: 1760778000000,
+  });
+});
+
+test('GeolocationCurrentPosition answers as the web does when location is refused', async () => {
+  injections.inject({ kind: 'location', value: { latitude: -33.92, longitude: 18.42 } });
+  injections.inject({ kind: 'permission', name: 'location', value: 'denied' });
+  await expect(GeolocationCurrentPosition({ params: {} })).resolves.toEqual({
+    code: 1,
+    error: 'PERMISSION_DENIED',
+    message: 'Location permission was denied.',
+  });
+});
+
+test('GeolocationCurrentPosition throws when the shell has no location to give', async () => {
+  await expect(GeolocationCurrentPosition({ params: {} })).rejects.toThrow(
+    'GeolocationCurrentPosition is not available on this phone yet: the shell has no device location. In Lowdefy Dev, inject a location.'
+  );
+});

package/src/actions/GetLocalStorage.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.
+*/
+
+import { type } from '@lowdefy/helpers';
+import parseStoredValue from '@lowdefy/actions-core/localStorage/parseStoredValue.js';
+import validateStorageKey from '@lowdefy/actions-core/localStorage/validateStorageKey.js';
+
+// The native body of actions-core's GetLocalStorage: reads the app's key from the device store
+// (expo-sqlite's key-value store), where the web reads localStorage.
+function GetLocalStorage({ globals, methods, params }) {
+  if (!type.isObject(params)) {
+    throw new Error('GetLocalStorage params should be an object.');
+  }
+  const { key } = params;
+  validateStorageKey({ actionType: 'GetLocalStorage', key });
+  const item = globals.storage.get(methods.getAppStorageKey(key));
+  if (type.isNone(item)) {
+    return params.default;
+  }
+  return parseStoredValue(item);
+}
+
+export default GetLocalStorage;

package/src/actions/RemoveLocalStorage.js

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

package/src/actions/ScrollTo.js

@@ -0,0 +1,66 @@
+/*
+  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';
+
+import measureInScrollView from './measureInScrollView.js';
+
+// Where the block's top lands, by scrollIntoView's `block` option. 'nearest' needs the current
+// scroll position, which a ScrollView does not report, so it scrolls as 'start' does.
+function getScrollTop({ align, element, viewport }) {
+  switch (align) {
+    case 'center':
+      return element.top - (viewport.height - element.height) / 2;
+    case 'end':
+      return element.top - viewport.height + element.height;
+    default:
+      return element.top;
+  }
+}
+
+// The native body of actions-core's ScrollTo: scrolls the page's ScrollView to a block's measured
+// position, or to `top` and `left` as window.scrollTo does. A block not on the page is left alone,
+// as on the web.
+async function ScrollTo({ globals, methods, params }) {
+  if (!type.isObject(params)) {
+    throw new Error('Invalid ScrollTo, check action params.');
+  }
+  const pageId = methods.getPageId();
+  const scrollView = globals.elements.find({ kind: 'scroll', pageId });
+  if (scrollView === null) {
+    return;
+  }
+  if (type.isNone(params.blockId)) {
+    scrollView.scrollTo({
+      animated: params.behavior === 'smooth',
+      x: params.left ?? 0,
+      y: params.top ?? 0,
+    });
+    return;
+  }
+  const view = globals.elements.find({ blockId: params.blockId, kind: 'view', pageId });
+  if (view === null) {
+    return;
+  }
+  const { element, viewport } = await measureInScrollView({ scrollView, view });
+  scrollView.scrollTo({
+    animated: params.options?.behavior === 'smooth',
+    x: 0,
+    y: Math.max(0, getScrollTop({ align: params.options?.block, element, viewport })),
+  });
+}
+
+export default ScrollTo;