@lowdefy/shell 0.0.0-experimental-20261019052246

package/src/locale/createShellLocale.js

@@ -0,0 +1,112 @@
+/*
+  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 { appStorageKey, type } from '@lowdefy/helpers';
+
+import loadDayjsLocale from './loadDayjsLocale.js';
+import resolveActiveLocale from './resolveActiveLocale.js';
+
+/**
+ * The locale of one app in the shell, kept as the web client keeps it (useLocale): the app's
+ * i18n config from the mobile root, the person's choice that SetLocale sets and the device store
+ * keeps under the app's key, and the device's locale.
+ *
+ * `apply` points the app at its active locale: `lowdefy.i18n` (read by `_t`, `_locale` and
+ * translate), the window members the engine trace reads, and the dayjs locale `_dayjs` formats
+ * with. Screens call it as they render and re-render on `subscribe`.
+ *
+ * It sets `window.__lowdefy_setLocale`, which actions-core's SetLocale calls.
+ *
+ * @param {Object} params
+ * @param {() => string[]} params.getDeviceLocales
+ * @param {Object} params.globals The app's host globals.
+ * @param {Object} params.session The app's session (createAppSession).
+ * @param {Object} params.storage The device store.
+ */
+function createShellLocale({ getDeviceLocales, globals, session, storage }) {
+  const listeners = new Set();
+  let version = 0;
+
+  function getStorageKey() {
+    const { rootConfig } = session.getState();
+    return appStorageKey({
+      basePath: '',
+      name: 'lowdefy_locale',
+      slug: rootConfig.lowdefyApp.slug,
+    });
+  }
+
+  // A host store may throw when the platform blocks storage, as the core allows; the choice then
+  // lasts only while the app runs.
+  function readPreference() {
+    try {
+      return storage.get(getStorageKey()) ?? 'auto';
+    } catch {
+      return 'auto';
+    }
+  }
+
+  function writePreference(preference) {
+    try {
+      if (preference === 'auto') {
+        storage.remove(getStorageKey());
+        return;
+      }
+      storage.set(getStorageKey(), preference);
+    } catch {
+      // See readPreference.
+    }
+  }
+
+  function apply() {
+    const { lowdefy, rootConfig } = session.getState();
+    const { i18n } = rootConfig;
+    if (type.isNone(i18n.defaultLocale)) {
+      return;
+    }
+    const active = resolveActiveLocale({
+      deviceLocales: getDeviceLocales(),
+      i18n,
+      preference: readPreference(),
+    });
+    lowdefy.i18n = { ...i18n, active };
+    globals.window.__lowdefy_locale = active;
+    globals.window.__lowdefy_supported_locales = i18n.locales;
+    const dayjsId = i18n.locales.find((locale) => locale.code === active)?.dayjs;
+    if (type.isString(dayjsId)) {
+      loadDayjsLocale(dayjsId);
+    }
+  }
+
+  // Applied now, not on the next render: SetLocale updates the engine straight after.
+  function setPreference(code) {
+    writePreference(code ?? 'auto');
+    apply();
+    version += 1;
+    listeners.forEach((listener) => listener());
+  }
+
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  }
+
+  globals.window.__lowdefy_setLocale = setPreference;
+
+  return { apply, getVersion: () => version, setPreference, subscribe };
+}
+
+export default createShellLocale;

package/src/locale/createShellLocale.test.js

@@ -0,0 +1,74 @@
+/*
+  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 createMemoryStore from '../host/createMemoryStore.js';
+import createShellLocale from './createShellLocale.js';
+
+const i18n = {
+  defaultLocale: 'en-US',
+  locales: [
+    { code: 'en-US', dayjs: 'en' },
+    { code: 'af-ZA', dayjs: 'af' },
+  ],
+  messages: {},
+};
+
+function createLocale(rootI18n) {
+  const lowdefy = {};
+  const session = {
+    getState: () => ({ lowdefy, rootConfig: { i18n: rootI18n, lowdefyApp: { slug: 'field' } } }),
+  };
+  const globals = { window: {} };
+  const storage = createMemoryStore();
+  const locale = createShellLocale({
+    getDeviceLocales: () => ['en-ZA'],
+    globals,
+    session,
+    storage,
+  });
+  return { globals, locale, lowdefy, storage };
+}
+
+test('createShellLocale points lowdefy.i18n and the window at the active locale', () => {
+  const { globals, locale, lowdefy } = createLocale(i18n);
+  locale.apply();
+  expect(lowdefy.i18n).toEqual({ ...i18n, active: 'en-US' });
+  expect(globals.window.__lowdefy_locale).toBe('en-US');
+  expect(globals.window.__lowdefy_supported_locales).toBe(i18n.locales);
+});
+
+test('SetLocale sets the choice through the window, keeps it and tells the screens', () => {
+  const { globals, locale, lowdefy, storage } = createLocale(i18n);
+  const listener = jest.fn();
+  locale.subscribe(listener);
+  globals.window.__lowdefy_setLocale('af-ZA');
+  expect(lowdefy.i18n.active).toBe('af-ZA');
+  expect(storage.get('lowdefy:field::lowdefy_locale')).toBe('af-ZA');
+  expect(listener).toHaveBeenCalledTimes(1);
+  expect(locale.getVersion()).toBe(1);
+  globals.window.__lowdefy_setLocale('auto');
+  expect(storage.keys()).toEqual([]);
+  expect(lowdefy.i18n.active).toBe('en-US');
+});
+
+test('createShellLocale leaves an app without i18n alone', () => {
+  const { globals, locale, lowdefy } = createLocale({});
+  locale.apply();
+  expect(lowdefy.i18n).toBeUndefined();
+  expect(globals.window.__lowdefy_locale).toBeUndefined();
+});

package/src/locale/dayjsLocales.js

@@ -0,0 +1,165 @@
+/*
+  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/createDayjsLocales.mjs from the dayjs package the shell carries. Do not edit.
+
+const dayjsLocales = {
+  af: () => require('dayjs/locale/af.js'),
+  am: () => require('dayjs/locale/am.js'),
+  ar: () => require('dayjs/locale/ar.js'),
+  'ar-dz': () => require('dayjs/locale/ar-dz.js'),
+  'ar-iq': () => require('dayjs/locale/ar-iq.js'),
+  'ar-kw': () => require('dayjs/locale/ar-kw.js'),
+  'ar-ly': () => require('dayjs/locale/ar-ly.js'),
+  'ar-ma': () => require('dayjs/locale/ar-ma.js'),
+  'ar-sa': () => require('dayjs/locale/ar-sa.js'),
+  'ar-tn': () => require('dayjs/locale/ar-tn.js'),
+  az: () => require('dayjs/locale/az.js'),
+  be: () => require('dayjs/locale/be.js'),
+  bg: () => require('dayjs/locale/bg.js'),
+  bi: () => require('dayjs/locale/bi.js'),
+  bm: () => require('dayjs/locale/bm.js'),
+  bn: () => require('dayjs/locale/bn.js'),
+  'bn-bd': () => require('dayjs/locale/bn-bd.js'),
+  bo: () => require('dayjs/locale/bo.js'),
+  br: () => require('dayjs/locale/br.js'),
+  bs: () => require('dayjs/locale/bs.js'),
+  ca: () => require('dayjs/locale/ca.js'),
+  cs: () => require('dayjs/locale/cs.js'),
+  cv: () => require('dayjs/locale/cv.js'),
+  cy: () => require('dayjs/locale/cy.js'),
+  da: () => require('dayjs/locale/da.js'),
+  de: () => require('dayjs/locale/de.js'),
+  'de-at': () => require('dayjs/locale/de-at.js'),
+  'de-ch': () => require('dayjs/locale/de-ch.js'),
+  dv: () => require('dayjs/locale/dv.js'),
+  el: () => require('dayjs/locale/el.js'),
+  en: () => require('dayjs/locale/en.js'),
+  'en-au': () => require('dayjs/locale/en-au.js'),
+  'en-ca': () => require('dayjs/locale/en-ca.js'),
+  'en-gb': () => require('dayjs/locale/en-gb.js'),
+  'en-ie': () => require('dayjs/locale/en-ie.js'),
+  'en-il': () => require('dayjs/locale/en-il.js'),
+  'en-in': () => require('dayjs/locale/en-in.js'),
+  'en-nz': () => require('dayjs/locale/en-nz.js'),
+  'en-sg': () => require('dayjs/locale/en-sg.js'),
+  'en-tt': () => require('dayjs/locale/en-tt.js'),
+  eo: () => require('dayjs/locale/eo.js'),
+  es: () => require('dayjs/locale/es.js'),
+  'es-do': () => require('dayjs/locale/es-do.js'),
+  'es-mx': () => require('dayjs/locale/es-mx.js'),
+  'es-pr': () => require('dayjs/locale/es-pr.js'),
+  'es-us': () => require('dayjs/locale/es-us.js'),
+  et: () => require('dayjs/locale/et.js'),
+  eu: () => require('dayjs/locale/eu.js'),
+  fa: () => require('dayjs/locale/fa.js'),
+  fi: () => require('dayjs/locale/fi.js'),
+  fo: () => require('dayjs/locale/fo.js'),
+  fr: () => require('dayjs/locale/fr.js'),
+  'fr-ca': () => require('dayjs/locale/fr-ca.js'),
+  'fr-ch': () => require('dayjs/locale/fr-ch.js'),
+  fy: () => require('dayjs/locale/fy.js'),
+  ga: () => require('dayjs/locale/ga.js'),
+  gd: () => require('dayjs/locale/gd.js'),
+  gl: () => require('dayjs/locale/gl.js'),
+  'gom-latn': () => require('dayjs/locale/gom-latn.js'),
+  gu: () => require('dayjs/locale/gu.js'),
+  he: () => require('dayjs/locale/he.js'),
+  hi: () => require('dayjs/locale/hi.js'),
+  hr: () => require('dayjs/locale/hr.js'),
+  ht: () => require('dayjs/locale/ht.js'),
+  hu: () => require('dayjs/locale/hu.js'),
+  'hy-am': () => require('dayjs/locale/hy-am.js'),
+  id: () => require('dayjs/locale/id.js'),
+  is: () => require('dayjs/locale/is.js'),
+  it: () => require('dayjs/locale/it.js'),
+  'it-ch': () => require('dayjs/locale/it-ch.js'),
+  ja: () => require('dayjs/locale/ja.js'),
+  jv: () => require('dayjs/locale/jv.js'),
+  ka: () => require('dayjs/locale/ka.js'),
+  kk: () => require('dayjs/locale/kk.js'),
+  km: () => require('dayjs/locale/km.js'),
+  kn: () => require('dayjs/locale/kn.js'),
+  ko: () => require('dayjs/locale/ko.js'),
+  ku: () => require('dayjs/locale/ku.js'),
+  ky: () => require('dayjs/locale/ky.js'),
+  lb: () => require('dayjs/locale/lb.js'),
+  lo: () => require('dayjs/locale/lo.js'),
+  lt: () => require('dayjs/locale/lt.js'),
+  lv: () => require('dayjs/locale/lv.js'),
+  me: () => require('dayjs/locale/me.js'),
+  mi: () => require('dayjs/locale/mi.js'),
+  mk: () => require('dayjs/locale/mk.js'),
+  ml: () => require('dayjs/locale/ml.js'),
+  mn: () => require('dayjs/locale/mn.js'),
+  mr: () => require('dayjs/locale/mr.js'),
+  ms: () => require('dayjs/locale/ms.js'),
+  'ms-my': () => require('dayjs/locale/ms-my.js'),
+  mt: () => require('dayjs/locale/mt.js'),
+  my: () => require('dayjs/locale/my.js'),
+  nb: () => require('dayjs/locale/nb.js'),
+  ne: () => require('dayjs/locale/ne.js'),
+  nl: () => require('dayjs/locale/nl.js'),
+  'nl-be': () => require('dayjs/locale/nl-be.js'),
+  nn: () => require('dayjs/locale/nn.js'),
+  'oc-lnc': () => require('dayjs/locale/oc-lnc.js'),
+  'pa-in': () => require('dayjs/locale/pa-in.js'),
+  pl: () => require('dayjs/locale/pl.js'),
+  pt: () => require('dayjs/locale/pt.js'),
+  'pt-br': () => require('dayjs/locale/pt-br.js'),
+  rn: () => require('dayjs/locale/rn.js'),
+  ro: () => require('dayjs/locale/ro.js'),
+  ru: () => require('dayjs/locale/ru.js'),
+  rw: () => require('dayjs/locale/rw.js'),
+  sd: () => require('dayjs/locale/sd.js'),
+  se: () => require('dayjs/locale/se.js'),
+  si: () => require('dayjs/locale/si.js'),
+  sk: () => require('dayjs/locale/sk.js'),
+  sl: () => require('dayjs/locale/sl.js'),
+  sq: () => require('dayjs/locale/sq.js'),
+  sr: () => require('dayjs/locale/sr.js'),
+  'sr-cyrl': () => require('dayjs/locale/sr-cyrl.js'),
+  ss: () => require('dayjs/locale/ss.js'),
+  sv: () => require('dayjs/locale/sv.js'),
+  'sv-fi': () => require('dayjs/locale/sv-fi.js'),
+  sw: () => require('dayjs/locale/sw.js'),
+  ta: () => require('dayjs/locale/ta.js'),
+  te: () => require('dayjs/locale/te.js'),
+  tet: () => require('dayjs/locale/tet.js'),
+  tg: () => require('dayjs/locale/tg.js'),
+  th: () => require('dayjs/locale/th.js'),
+  tk: () => require('dayjs/locale/tk.js'),
+  'tl-ph': () => require('dayjs/locale/tl-ph.js'),
+  tlh: () => require('dayjs/locale/tlh.js'),
+  tr: () => require('dayjs/locale/tr.js'),
+  tzl: () => require('dayjs/locale/tzl.js'),
+  tzm: () => require('dayjs/locale/tzm.js'),
+  'tzm-latn': () => require('dayjs/locale/tzm-latn.js'),
+  'ug-cn': () => require('dayjs/locale/ug-cn.js'),
+  uk: () => require('dayjs/locale/uk.js'),
+  ur: () => require('dayjs/locale/ur.js'),
+  uz: () => require('dayjs/locale/uz.js'),
+  'uz-latn': () => require('dayjs/locale/uz-latn.js'),
+  vi: () => require('dayjs/locale/vi.js'),
+  'x-pseudo': () => require('dayjs/locale/x-pseudo.js'),
+  yo: () => require('dayjs/locale/yo.js'),
+  zh: () => require('dayjs/locale/zh.js'),
+  'zh-cn': () => require('dayjs/locale/zh-cn.js'),
+  'zh-hk': () => require('dayjs/locale/zh-hk.js'),
+  'zh-tw': () => require('dayjs/locale/zh-tw.js'),
+};
+
+export default dayjsLocales;

package/src/locale/getDeviceLocales.js

@@ -0,0 +1,23 @@
+/*
+  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 device's locale, which Hermes' Intl reads from the platform (iOS's NSLocale, Android's
+// default Locale).
+function getDeviceLocales() {
+  return [Intl.DateTimeFormat().resolvedOptions().locale];
+}
+
+export default getDeviceLocales;

package/src/locale/loadDayjsLocale.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 dayjs from 'dayjs';
+
+import dayjsLocales from './dayjsLocales.js';
+
+// Makes a dayjs locale the one _dayjs formats with, loading its data the first time. The dayjs
+// instance is the one @lowdefy/operators-dayjs imports. An id dayjs does not ship leaves the
+// locale as it is, as on the web.
+function loadDayjsLocale(id) {
+  if (!Object.hasOwn(dayjsLocales, id)) {
+    return;
+  }
+  dayjsLocales[id]();
+  dayjs.locale(id);
+}
+
+export default loadDayjsLocale;

package/src/locale/resolveActiveLocale.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.
+*/
+
+// The first device locale the app supports, by exact code, then by language.
+function pickBest({ candidates, supported }) {
+  for (const candidate of candidates) {
+    if (supported.includes(candidate)) return candidate;
+    const language = candidate.split('-')[0];
+    const match = supported.find((code) => code.split('-')[0] === language);
+    if (match) return match;
+  }
+  return undefined;
+}
+
+/**
+ * The app's active locale, as the web client picks it (useLocale): the person's choice (SetLocale)
+ * when the app supports it, else the device's locale the app supports best, else the app's
+ * default. Undefined for an app without i18n.
+ *
+ * @param {Object} params
+ * @param {string[]} params.deviceLocales The device's locales, preferred first.
+ * @param {Object} params.i18n The app's i18n config: `{ defaultLocale, locales }`.
+ * @param {string} params.preference A locale code, or 'auto'.
+ */
+function resolveActiveLocale({ deviceLocales, i18n, preference }) {
+  const supported = (i18n.locales ?? []).map((locale) => locale.code);
+  if (preference !== 'auto' && supported.includes(preference)) {
+    return preference;
+  }
+  return pickBest({ candidates: deviceLocales, supported }) ?? i18n.defaultLocale;
+}
+
+export default resolveActiveLocale;

package/src/locale/resolveActiveLocale.test.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 resolveActiveLocale from './resolveActiveLocale.js';
+
+const i18n = {
+  defaultLocale: 'en-US',
+  locales: [{ code: 'en-US' }, { code: 'af-ZA' }, { code: 'pt-BR' }],
+};
+
+test('resolveActiveLocale takes the person choice when the app supports it', () => {
+  expect(resolveActiveLocale({ deviceLocales: ['pt-BR'], i18n, preference: 'af-ZA' })).toBe(
+    'af-ZA'
+  );
+  expect(resolveActiveLocale({ deviceLocales: ['pt-BR'], i18n, preference: 'de-DE' })).toBe(
+    'pt-BR'
+  );
+});
+
+test('resolveActiveLocale matches the device locale by code, then by language', () => {
+  expect(resolveActiveLocale({ deviceLocales: ['pt-BR'], i18n, preference: 'auto' })).toBe('pt-BR');
+  expect(resolveActiveLocale({ deviceLocales: ['pt-PT'], i18n, preference: 'auto' })).toBe('pt-BR');
+});
+
+test('resolveActiveLocale falls back to the app default', () => {
+  expect(resolveActiveLocale({ deviceLocales: ['ja-JP'], i18n, preference: 'auto' })).toBe('en-US');
+});

package/src/navigation/SlotContext.js

@@ -0,0 +1,24 @@
+/*
+  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 } from 'react';
+
+// The index of the frame group (app/(t0,t1,t2,t3,t4)) a screen lives in, which its group layout
+// provides from the segment Expo Router gives it. A screen cannot read it from useSegments: those
+// are the focused route's, so every tab rendered at once would take the focused tab's index.
+const SlotContext = createContext(0);
+
+export default SlotContext;

package/src/navigation/frameSlots.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.
+*/
+
+// The route groups the frame's screens live in: app/(t0,t1,t2,t3,t4) is one set of routes shared
+// by five groups. With a tabs frame each tab is a group, with its own stack; mobile.menus.tabs has
+// at most five items. A drawer or stack frame uses the first group only.
+const FRAME_SLOTS = ['t0', 't1', 't2', 't3', 't4'];
+
+function getSlotIndex(segment) {
+  return FRAME_SLOTS.indexOf(String(segment).replace(/^\(|\)$/g, ''));
+}
+
+export { getSlotIndex };
+export default FRAME_SLOTS;

package/src/navigation/getFrame.js

@@ -0,0 +1,30 @@
+/*
+  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 frame an app's mobile menus declare: { kind: 'tabs', items }, { kind: 'drawer', items } or
+// { kind: 'stack' }. The server drops the items a caller may not open, so a tabs frame left with
+// fewer than two items, or a drawer with none, falls back to a stack.
+function getFrame(menus) {
+  if ((menus?.tabs?.length ?? 0) >= 2) {
+    return { kind: 'tabs', items: menus.tabs };
+  }
+  if ((menus?.drawer?.length ?? 0) >= 1) {
+    return { kind: 'drawer', items: menus.drawer };
+  }
+  return { kind: 'stack', items: [] };
+}
+
+export default getFrame;

package/src/navigation/getInitialScreenOptions.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 { type } from '@lowdefy/helpers';
+
+function noop() {}
+
+/**
+ * The header options a Screen page's config gives before the page renders, in the shape a Screen
+ * reports (client-native screen/Screen.js): the parts that size the bar (a large title, a search
+ * field) and how it is drawn (a backgroundTint's clear bar), from literal properties. The Screen
+ * reports its full options once it renders; these set the bar first, so the page's scroll view is
+ * first laid out under the bar it will have. iOS keeps a large title collapsed when the page's
+ * scroll view was laid out under a standard bar before the large title came.
+ *
+ * @param {Object} params
+ * @param {Object} params.pageConfig The page config, as the server sends it.
+ * @returns {Object|null} The options, or null for a page that is not a Screen.
+ */
+function getInitialScreenOptions({ pageConfig }) {
+  if (pageConfig.type !== 'Screen') {
+    return null;
+  }
+  const properties = pageConfig.properties ?? {};
+  const headerSearch = properties.headerSearch;
+  return {
+    backgroundTint: !type.isNone(properties.backgroundTint),
+    headerActions: [],
+    headerBottom: false,
+    headerLeft: undefined,
+    headerRight: undefined,
+    headerSearch: type.isObject(headerSearch)
+      ? {
+          autoFocus: false,
+          hideWhenScrolling: headerSearch.hideWhenScrolling === true,
+          onCancel: noop,
+          onChangeText: noop,
+          onSearch: noop,
+          placeholder: type.isString(headerSearch.placeholder)
+            ? headerSearch.placeholder
+            : undefined,
+        }
+      : undefined,
+    largeTitle: properties.largeTitle === true,
+    presentation: type.isString(properties.presentation) ? properties.presentation : 'card',
+    title: type.isString(properties.title) ? properties.title : undefined,
+  };
+}
+
+export default getInitialScreenOptions;