@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/cli/setup/steps/env.js

@@ -0,0 +1,245 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { exportsType, importPath } = require('../../typescript');
+
+/** @typedef {import('../../changes').FileChange} FileChange */
+/** @typedef {import('../../typescript').TS} TS */
+
+/** The file that types the commands with the app's screens. */
+const ENV_FILE = 'navigation-env.d.ts';
+
+const HEADER = "// Made by apex-navigation setup: the types of the app's screens";
+
+/**
+ * Where the navigation is: its module, the name it is exported under (`default` for a default export), and whether
+ * the module exports the type of the app's context, `AppContext`.
+ * @typedef {{ file: string; exported: string; context: boolean }} NavigationTarget
+ */
+
+/**
+ * The text of navigation-env.d.ts for the navigation of the app.
+ * @param {string} root
+ * @param {NavigationTarget} navigation
+ * @returns {string}
+ */
+function envText(root, { file, exported, context }) {
+  const module = importPath(path.join(root, ENV_FILE), file);
+  const lines = [
+    HEADER,
+    "// for the navigation's commands. Don't edit.",
+    "declare module '@apexnative/navigation' {",
+    '  interface Register {',
+    `    app: typeof import('${module}').${exported};`,
+    ...(context ? [`    context: import('${module}').AppContext;`] : []),
+    '  }',
+    '}',
+    'export {};',
+  ];
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * The navigation of an app whose entry point is set up: from the import of the entry point, read with the app's
+ * TypeScript.
+ * @param {TS} ts
+ * @param {{ file: string; exported: string }} imported
+ * @returns {NavigationTarget}
+ */
+function targetOf(ts, imported) {
+  return { ...imported, context: exportsType(ts, imported.file, 'AppContext') };
+}
+
+/**
+ * navigation-env.d.ts and, when its `include` leaves the file out, tsconfig.json: the commands typed with the app's
+ * screens. Nothing in an app without tsconfig.json: its names are plain strings.
+ * @param {string} root
+ * @param {NavigationTarget | undefined} navigation undefined when the entry point isn't set up, so nothing says where
+ *   the navigation is yet
+ * @param {TS | undefined} ts the app's TypeScript, for a tsconfig.json with comments
+ * @returns {FileChange[]}
+ */
+function planEnv(root, navigation, ts) {
+  const tsconfig = path.join(root, 'tsconfig.json');
+  if (!fs.existsSync(tsconfig) || !navigation) return [];
+  const file = path.join(root, ENV_FILE);
+  const next = envText(root, navigation);
+  /** @type {FileChange[]} */
+  const changes = [];
+  if (!fs.existsSync(file)) {
+    changes.push({
+      name: ENV_FILE,
+      platform: 'js',
+      file,
+      status: 'create',
+      next,
+      note: 'typed commands',
+    });
+  } else {
+    const before = fs.readFileSync(file, 'utf8');
+    if (before === next) {
+      changes.push({
+        name: ENV_FILE,
+        platform: 'js',
+        file,
+        status: 'done',
+        note: 'already set up',
+      });
+    } else if (before.startsWith(HEADER)) {
+      changes.push({
+        name: ENV_FILE,
+        platform: 'js',
+        file,
+        status: 'change',
+        before,
+        next,
+        note: navigation.context ? 'the navigation and its context' : 'where the navigation is',
+      });
+    } else {
+      changes.push({
+        name: ENV_FILE,
+        platform: 'js',
+        file,
+        status: 'manual',
+        note: 'written by hand, see below',
+        howTo: `Make ${ENV_FILE} what setup writes, or delete it and run setup again:\n\n${next}`,
+      });
+    }
+  }
+  const include = planInclude(tsconfig, ts);
+  if (include) changes.push(include);
+  return changes;
+}
+
+/**
+ * tsconfig.json with navigation-env.d.ts in its `include`, when it has one that leaves the file out; undefined when
+ * TypeScript takes the file already.
+ * @param {string} tsconfig
+ * @param {TS | undefined} ts
+ * @returns {FileChange | undefined}
+ */
+function planInclude(tsconfig, ts) {
+  const before = fs.readFileSync(tsconfig, 'utf8');
+  const config = readJson(before, ts);
+  const howTo = `Add "${ENV_FILE}" to "include" of tsconfig.json, so TypeScript reads it.`;
+  if (!config) {
+    return {
+      name: 'tsconfig.json',
+      platform: 'js',
+      file: tsconfig,
+      status: 'manual',
+      note: "couldn't be read",
+      howTo,
+    };
+  }
+  // Without `include`, TypeScript takes every file of the folder; with `files` only, none but those.
+  if (!Array.isArray(config.include)) {
+    if (!Array.isArray(config.files) || config.files.includes(ENV_FILE)) return undefined;
+    return {
+      name: 'tsconfig.json',
+      platform: 'js',
+      file: tsconfig,
+      status: 'manual',
+      note: 'lists its files',
+      howTo: `Add "${ENV_FILE}" to "files" of tsconfig.json, so TypeScript reads it.`,
+    };
+  }
+  if (config.include.some((/** @type {unknown} */ pattern) => takes(pattern, ENV_FILE))) {
+    return undefined;
+  }
+  const next = addToArray(before, 'include', ENV_FILE);
+  if (!next) {
+    return {
+      name: 'tsconfig.json',
+      platform: 'js',
+      file: tsconfig,
+      status: 'manual',
+      note: 'written in a way the CLI keeps',
+      howTo,
+    };
+  }
+  return {
+    name: 'tsconfig.json',
+    platform: 'js',
+    file: tsconfig,
+    status: 'change',
+    before,
+    next,
+    note: `${ENV_FILE} in include`,
+  };
+}
+
+/**
+ * A tsconfig.json as an object: plain JSON, or with comments and trailing commas through the app's TypeScript.
+ * @param {string} text
+ * @param {TS | undefined} ts
+ * @returns {any}
+ */
+function readJson(text, ts) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    if (!ts) return undefined;
+    const { config, error } = ts.parseConfigFileTextToJson('tsconfig.json', text);
+    return error ? undefined : config;
+  }
+}
+
+/**
+ * Whether a pattern of `include` takes a file of the app's root: TypeScript's wildcards (`*`, `?`, and `**` for any folders), or a
+ * folder and what is under it.
+ * @param {unknown} pattern
+ * @param {string} file
+ */
+function takes(pattern, file) {
+  if (typeof pattern !== 'string') return false;
+  const normalized = pattern.replace(/^\.\//, '');
+  if (!/[*?]/.test(normalized)) {
+    return normalized === file || normalized === '.' || normalized === '';
+  }
+  const source = normalized
+    .split(/(\*\*\/|\*|\?)/)
+    .map((part) => {
+      if (part === '**/') return '(?:[^/]+/)*';
+      if (part === '*') return '[^/]*';
+      if (part === '?') return '[^/]';
+      return part.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    })
+    .join('');
+  return new RegExp(`^${source}$`).test(file);
+}
+
+/**
+ * The text of a JSON file with a string added last to the array of a top key, written as the array is: on one line, or
+ * one item per line with their indentation. Undefined when the array isn't found in the text.
+ * @param {string} text
+ * @param {string} key
+ * @param {string} item
+ * @returns {string | undefined}
+ */
+function addToArray(text, key, item) {
+  const found = new RegExp(String.raw`"${key}"\s*:\s*\[([^\]]*)\]`).exec(text);
+  if (!found) return undefined;
+  const [whole, inside] = found;
+  const start = found.index;
+  const quoted = JSON.stringify(item);
+  /** @type {string} */
+  let array;
+  if (!inside.includes('\n') || inside.trim() === '') {
+    const items = inside.trim().replace(/,$/, '');
+    array = `[${items ? `${items}, ` : ''}${quoted}]`;
+  } else {
+    const lines = inside.split('\n');
+    const last = [...lines].reverse().find((line) => line.trim() !== '') ?? '';
+    const indent = /^[ \t]*/.exec(last)?.[0] ?? '  ';
+    const closing = /\n([ \t]*)$/.exec(inside)?.[1] ?? '';
+    const items = inside.trimEnd().replace(/,$/, '');
+    array = `[${items},\n${indent}${quoted}\n${closing}]`;
+  }
+  const head = whole.slice(0, whole.indexOf('['));
+  return text.slice(0, start) + head + array + text.slice(start + whole.length);
+}
+
+module.exports = { ENV_FILE, planEnv, envText, targetOf, takes, addToArray };

package/cli/setup/steps/infoPlist.js

@@ -0,0 +1,39 @@
+// @ts-check
+'use strict';
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const HOW_TO = `Let each screen set the status bar (the statusBar option):
+
+  <key>UIViewControllerBasedStatusBarAppearance</key>
+  <true/>`;
+
+const KEY = /(<key>UIViewControllerBasedStatusBarAppearance<\/key>\s*)<(true|false)\s*\/>/;
+
+/**
+ * Info.plist: the status bar follows the screen on top.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planInfoPlist(text) {
+  const found = KEY.exec(text);
+  if (found?.[2] === 'true') return { status: 'done', note: 'already set up' };
+  if (found)
+    return {
+      status: 'change',
+      next: text.replace(KEY, '$1<true/>'),
+      note: 'status bar per screen',
+    };
+  // The key goes last in the top dictionary, indented as its other keys.
+  const end = /\n<\/dict>\s*<\/plist>\s*$/.exec(text);
+  if (!end) return { status: 'manual', note: 'changed by hand, see below', howTo: HOW_TO };
+  const indent = /\n([ \t]+)<key>/.exec(text)?.[1] ?? '\t';
+  const key = `\n${indent}<key>UIViewControllerBasedStatusBarAppearance</key>\n${indent}<true/>`;
+  return {
+    status: 'change',
+    next: text.slice(0, end.index) + key + text.slice(end.index),
+    note: 'status bar per screen',
+  };
+}
+
+module.exports = { planInfoPlist };

package/cli/setup/steps/mainActivity.js

@@ -0,0 +1,60 @@
+// @ts-check
+'use strict';
+
+const { addImport, removeUnusedImports } = require('../source');
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const HOW_TO = `Extend NavigationActivity. The screens come from JavaScript, so getMainComponentName and
+createReactActivityDelegate go.
+
+  import dev.apexnative.navigation.NavigationActivity
+
+  class MainActivity : NavigationActivity()`;
+
+// The members of the template, each with the comment above it.
+const DOC = String.raw`(?:\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*)?`;
+const MAIN_COMPONENT_NAME = new RegExp(
+  String.raw`\n?[ \t]*${DOC}override\s+fun\s+getMainComponentName\(\)\s*:\s*String\s*` +
+    String.raw`(?:=\s*"[^"]*"|\{\s*return\s+"[^"]*"\s*\})[ \t]*\n`
+);
+const ACTIVITY_DELEGATE = new RegExp(
+  String.raw`\n?[ \t]*${DOC}override\s+fun\s+createReactActivityDelegate\(\)\s*:\s*ReactActivityDelegate\s*` +
+    String.raw`(?:=\s*DefaultReactActivityDelegate\([^)]*\)|\{\s*return\s+DefaultReactActivityDelegate\([^)]*\)\s*\})` +
+    String.raw`[ \t]*\n`
+);
+
+// Imports of the template that the change leaves unused.
+const TEMPLATE_IMPORTS = [
+  'com.facebook.react.ReactActivity',
+  'com.facebook.react.ReactActivityDelegate',
+  'com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.fabricEnabled',
+  'com.facebook.react.defaults.DefaultReactActivityDelegate',
+];
+
+/**
+ * MainActivity.kt: the activity becomes a NavigationActivity.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planMainActivity(text) {
+  if (/:\s*NavigationActivity\(\)/.test(text)) return { status: 'done', note: 'already set up' };
+  const header = /class\s+(\w+)\s*:\s*ReactActivity\(\)/;
+  const manual = /** @type {StepResult} */ ({
+    status: 'manual',
+    note: 'changed by hand, see below',
+    howTo: HOW_TO,
+  });
+  if (!header.test(text)) return manual;
+  let next = text.replace(MAIN_COMPONENT_NAME, '').replace(ACTIVITY_DELEGATE, '');
+  // A delegate of the app's own: what it does has to move elsewhere by hand.
+  if (/\b(getMainComponentName|createReactActivityDelegate)\b/.test(next)) return manual;
+  next = next.replace(header, 'class $1 : NavigationActivity()');
+  next = next.replace(/(class\s+\w+\s*:\s*NavigationActivity\(\))\s*\{\s*\}/, '$1');
+  // Added first: with the template's imports gone the file would have none to sort it among.
+  next = addImport(next, 'import dev.apexnative.navigation.NavigationActivity', { sorted: true });
+  next = removeUnusedImports(next, TEMPLATE_IMPORTS);
+  return { status: 'change', next, note: 'NavigationActivity' };
+}
+
+module.exports = { planMainActivity };

package/cli/setup/steps/mainApplication.js

@@ -0,0 +1,58 @@
+// @ts-check
+'use strict';
+
+const { addImport, codeOf, removeUnusedImports } = require('../source');
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const HOW_TO = `Extend NavigationApplication. It loads React Native itself, so loadReactNative(this) goes:
+calling it again crashes the app on start.
+
+  import dev.apexnative.navigation.NavigationApplication
+
+  class MainApplication : NavigationApplication() {
+    override val reactHost: ReactHost by lazy { ... }   // as it is
+  }`;
+
+// Imports of the template that the change leaves unused.
+const TEMPLATE_IMPORTS = [
+  'android.app.Application',
+  'com.facebook.react.ReactApplication',
+  'com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative',
+];
+
+/**
+ * MainApplication.kt: the application becomes a NavigationApplication.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planMainApplication(text) {
+  const manual = /** @type {StepResult} */ ({
+    status: 'manual',
+    note: 'changed by hand, see below',
+    howTo: HOW_TO,
+  });
+  if (/:\s*NavigationApplication\(\)/.test(text)) {
+    return /\bloadReactNative\s*\(/.test(codeOf(text))
+      ? manual
+      : { status: 'done', note: 'already set up' };
+  }
+  const header = /class\s+(\w+)\s*:\s*Application\(\)\s*,\s*ReactApplication\b/;
+  if (!header.test(text)) return manual;
+  let next = text.replace(header, 'class $1 : NavigationApplication()');
+  // The template's onCreate only loads React Native, so it goes; another one keeps the rest of its code.
+  next = next.replace(
+    /\n\n?[ \t]*override\s+fun\s+onCreate\(\)\s*\{\s*super\.onCreate\(\)\s*loadReactNative\(this\)\s*\}/,
+    ''
+  );
+  next = next.replace(/^[ \t]*loadReactNative\(this\)[ \t]*\r?\n/m, '');
+  if (/\bloadReactNative\s*\(/.test(codeOf(next))) return manual;
+  // Added first: with the template's imports gone the file would have none to sort it among.
+  next = addImport(next, 'import dev.apexnative.navigation.NavigationApplication', {
+    sorted: true,
+  });
+  next = removeUnusedImports(next, TEMPLATE_IMPORTS);
+  return { status: 'change', next, note: 'NavigationApplication' };
+}
+
+module.exports = { planMainApplication };

package/cli/setup/steps/manifest.js

@@ -0,0 +1,38 @@
+// @ts-check
+'use strict';
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const APPLICATION = /<application\b[^>]*>/;
+const FLAG = /android:enableOnBackInvokedCallback\s*=\s*(["'])(.*?)\1/;
+const ATTRIBUTE = 'android:enableOnBackInvokedCallback="true"';
+
+const HOW_TO = `Add ${ATTRIBUTE} to the <application> element of AndroidManifest.xml: the system then plays its back animations, such as back to the home screen from the first screen.`;
+
+/**
+ * AndroidManifest.xml: the app takes part in predictive back, so the system plays its back animations, back to the home
+ * screen from the first screen among them. Android 16 turns it on for an app that targets API 36; an app that targets
+ * less opts in here. A value the app set itself stays.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planManifest(text) {
+  const tag = APPLICATION.exec(text)?.[0];
+  if (!tag) return { status: 'manual', note: 'no <application> element, see below', howTo: HOW_TO };
+  const value = FLAG.exec(tag)?.[2];
+  if (value === 'true') return { status: 'done', note: 'already set up' };
+  if (value !== undefined) return { status: 'done', note: "the app's own setting" };
+  // On a line of its own before the tag closes, as the template has its attributes.
+  const end = tag.endsWith('/>') ? '/>' : '>';
+  const head = tag.slice(0, -end.length).trimEnd();
+  const indent = /\n([ \t]+)\S[^\n]*$/.exec(head)?.[1];
+  const attribute = indent ? `\n${indent}${ATTRIBUTE}` : ` ${ATTRIBUTE}`;
+  return {
+    status: 'change',
+    // A function, so a `$` in the app's own attributes stays as it is.
+    next: text.replace(tag, () => `${head}${attribute}${end}`),
+    note: 'predictive back',
+  };
+}
+
+module.exports = { planManifest, HOW_TO };

package/cli/setup/steps/styles.js

@@ -0,0 +1,29 @@
+// @ts-check
+'use strict';
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const APP_THEME = /(<style\s+name="AppTheme"\s+parent=")([^"]*)(")/;
+
+// The theme of React Native's template: AppCompat, light or dark with the system, with no Material 3 colors. A
+// light-only theme stays: Theme.ApexNavigation would make the app follow dark mode.
+const TEMPLATE_PARENT = 'Theme.AppCompat.DayNight.NoActionBar';
+
+/**
+ * styles.xml: the app's theme inherits Theme.ApexNavigation, Material 3 in neutral grays. A theme of the app's own
+ * stays: the navigation takes its Material 3 colors, or its own neutral ones when it has none.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planStyles(text) {
+  const parent = APP_THEME.exec(text)?.[2];
+  if (parent === 'Theme.ApexNavigation') return { status: 'done', note: 'already set up' };
+  if (parent !== TEMPLATE_PARENT) return { status: 'done', note: "the app's own theme" };
+  return {
+    status: 'change',
+    next: text.replace(APP_THEME, '$1Theme.ApexNavigation$3'),
+    note: 'Theme.ApexNavigation',
+  };
+}
+
+module.exports = { planStyles };

package/cli/setup/steps/types.js

@@ -0,0 +1,14 @@
+// @ts-check
+'use strict';
+
+/**
+ * What a step does with a file:
+ * - change: the file looks like the template, `next` is the file set up;
+ * - done: the file is set up already;
+ * - manual: the file was changed by hand and the step can't tell how; `howTo` says what to change.
+ * @typedef {{ status: 'change'; next: string; note: string }
+ *   | { status: 'done'; note: string }
+ *   | { status: 'manual'; note: string; howTo: string }} StepResult
+ */
+
+module.exports = {};