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

package/cli/codegen/swift.js

@@ -0,0 +1,342 @@
+// @ts-check
+'use strict';
+
+const { swiftCommands } = require('./commands');
+const { memberName, swiftIdentifier, swiftString } = require('./names');
+
+/** @typedef {import('./read').Model} Model */
+/** @typedef {import('./read').Field} Field */
+/** @typedef {import('./read').NativeScreenModel} NativeScreenModel */
+/** @typedef {import('../config').IosKind} IosKind */
+
+const HEADER = `// Generated by \`npx apex-navigation codegen\` from the native screens of the app. Don't edit it: change the props in
+// TypeScript and run the command again.`;
+
+/**
+ * The Swift file of the app's native screens: their props, the screen and navigation types their views take, and the
+ * list the navigation registers as it starts. A screen with a `kind` is registered: its view (SwiftUI) or view
+ * controller (UIKit) is `<Name>Screen` / `<Name>ViewController`, made with `screen:`.
+ * The typed commands come after them: the screens of `screens` as an enum, and the commands that take one.
+ * @param {{ screen: NativeScreenModel; kind?: IosKind }[]} screens
+ * @param {import('./read').CommandScreenModel[]} [commands]
+ * @returns {string}
+ */
+function swiftFile(screens, commands = []) {
+  const swiftUI = screens.some(({ kind }) => kind === 'swiftui');
+  const imports = ['ApexNavigation', 'Combine', ...(swiftUI ? ['SwiftUI'] : []), 'UIKit'];
+  return [
+    HEADER,
+    '',
+    imports.map((name) => `import ${name}`).join('\n'),
+    '',
+    registry(screens),
+    ...screens.map(({ screen }) => props(screen)),
+    SHARED,
+    ...(commands.length > 0 ? [swiftCommands(commands)] : []),
+  ].join('\n');
+}
+
+/**
+ * @param {{ screen: NativeScreenModel; kind?: IosKind }[]} screens
+ */
+function registry(screens) {
+  const registered = screens.flatMap(({ screen, kind }) => {
+    if (!kind) return [];
+    const name = screen.nativeName;
+    const screenValue = `NativeScreen(context, props: ${name}Props.init)`;
+    const made =
+      kind === 'swiftui'
+        ? `UIHostingController(rootView: ${name}Screen(screen: ${screenValue}))`
+        : `${name}ViewController(screen: ${screenValue})`;
+    // The navigation makes native screens on the main thread.
+    return [
+      `    ApexNavigation.registerNativeScreen(${swiftString(name)}) { context in`,
+      `      MainActor.assumeIsolated { ${made} }`,
+      '    }',
+    ];
+  });
+  return `// MARK: - Native screens
+
+/// The native screens of the app, which the navigation registers itself as it starts.
+@objc(ApexNavigationGeneratedScreens)
+final class ApexNavigationGeneratedScreens: NSObject {
+  @objc static func registerScreens() {
+${registered.length > 0 ? registered.join('\n') : '    // None: `npx apex-navigation screen <Name> --native` adds one.'}
+  }
+}
+`;
+}
+
+/**
+ * The props of one screen: a struct with its enums and objects inside, read from the screen's context.
+ * @param {NativeScreenModel} screen
+ */
+function props(screen) {
+  const name = `${screen.nativeName}Props`;
+  const enums = screen.enums.map(
+    (item) =>
+      `  enum ${item.name}: String, CaseIterable {\n${item.values
+        .map((value) => `    case ${swiftIdentifier(memberName(value))} = ${swiftString(value)}`)
+        .join('\n')}\n  }\n`
+  );
+  const objects = screen.objects.map((object) => {
+    const members = object.fields.map((field) => `    ${declaration(field)}`).join('\n');
+    const reads = object.fields
+      .map(
+        (field) =>
+          `      ${swiftIdentifier(field.name)} = ${read(field, `fields[${swiftString(field.name)}]`)}`
+      )
+      .join('\n');
+    const json = object.fields
+      .map(
+        (field) =>
+          `${swiftString(field.name)}: ${encode(field.type, swiftIdentifier(field.name), field.optional)}`
+      )
+      .join(', ');
+    return `  struct ${object.name} {
+${members}
+
+    init(_ value: Any?) {
+      let fields = value as? [String: Any] ?? [:]
+${reads}
+    }
+
+    var json: [String: Any] { [${json || ':'}] }
+  }
+`;
+  });
+  const members = screen.fields.flatMap((field) => [
+    ...docLines(field.doc, '  '),
+    `  ${declaration(field)}`,
+  ]);
+  const reads = screen.fields.map(
+    (field) =>
+      `    ${swiftIdentifier(field.name)} = ${
+        field.type.kind !== 'function'
+          ? read(field, `props[${swiftString(field.name)}]`)
+          : field.optional
+            ? `context.functions.contains(${swiftString(field.name)}) ? ${call(field.name, field.type)} : nil`
+            : call(field.name, field.type)
+      }`
+  );
+  return `// MARK: - ${screen.nativeName}
+
+/// The props of the native screen \`${screen.nativeName}\` (${screen.file}).
+struct ${name} {
+${[...enums, ...objects].join('\n')}${enums.length + objects.length > 0 ? '\n' : ''}${members.join('\n')}
+
+  init(_ context: NativeScreenContext) {
+    let props = context.props
+${reads.join('\n')}
+  }
+}
+`;
+}
+
+/**
+ * @param {Field} field
+ */
+function declaration(field) {
+  const type = swiftType(field.type);
+  const optional = field.type.kind === 'function' ? `(${type})?` : `${type}?`;
+  return `let ${swiftIdentifier(field.name)}: ${field.optional ? optional : type}`;
+}
+
+/**
+ * @param {Model} model
+ * @returns {string}
+ */
+function swiftType(model) {
+  switch (model.kind) {
+    case 'string':
+      return 'String';
+    case 'number':
+      return model.int ? 'Int' : 'Double';
+    case 'boolean':
+      return 'Bool';
+    case 'enum':
+    case 'object':
+      return model.name;
+    case 'array':
+      return `[${swiftType(model.element)}]`;
+    case 'function':
+      return `(${model.parameters.map(({ type }) => swiftType(type)).join(', ')}) async throws -> ${
+        model.result ? swiftType(model.result) : 'Void'
+      }`;
+  }
+}
+
+/**
+ * The expression that reads a field from a value of JS.
+ * @param {Field} field
+ * @param {string} value
+ */
+function read(field, value) {
+  if (!field.optional) return decode(field.type, value);
+  if (field.type.kind === 'enum')
+    return `(${value} as? String).flatMap(${field.type.name}.init(rawValue:))`;
+  return `isPresent(${value}) ? ${decode(field.type, value)} : nil`;
+}
+
+/**
+ * @param {Model} model
+ * @param {string} value
+ * @returns {string}
+ */
+function decode(model, value) {
+  switch (model.kind) {
+    case 'string':
+      return `decodeString(${value})`;
+    case 'number':
+      return model.int ? `decodeInt(${value})` : `decodeNumber(${value})`;
+    case 'boolean':
+      return `decodeBool(${value})`;
+    case 'enum':
+      return `${model.name}(rawValue: decodeString(${value})) ?? ${model.name}.allCases[0]`;
+    case 'object':
+      return `${model.name}(${value})`;
+    case 'array':
+      return `decodeArray(${value}) { ${decode(model.element, '$0')} }`;
+    case 'function':
+      return 'nil';
+  }
+}
+
+/**
+ * The value JS gets for a value of Swift: an argument of a function, or a field of an object.
+ * @param {Model} model
+ * @param {string} value
+ * @param {boolean} [optional]
+ * @returns {string}
+ */
+function encode(model, value, optional = false) {
+  if (optional) return `(${value}.map { ${encode(model, '$0')} as Any } ?? NSNull())`;
+  switch (model.kind) {
+    case 'enum':
+      return `${value}.rawValue`;
+    case 'object':
+      return `${value}.json`;
+    case 'array':
+      return `${value}.map { ${encode(model.element, '$0')} }`;
+    default:
+      return value;
+  }
+}
+
+/**
+ * A function of the props: a closure that calls it in JS with its arguments and reads what it resolved with.
+ * @param {string} name
+ * @param {Extract<Model, { kind: 'function' }>} model
+ */
+function call(name, model) {
+  const parameters = model.parameters.map(({ name: parameter }) =>
+    swiftIdentifier(memberName(parameter))
+  );
+  const head = parameters.length > 0 ? `${parameters.join(', ')} in ` : '';
+  const args = model.parameters
+    .map(({ type }, index) => encode(type, parameters[index]))
+    .join(', ');
+  const called = `context.call(${swiftString(name)}, arguments: [${args}])`;
+  return model.result
+    ? `{ ${head}try await ${decode(model.result, called)} }`
+    : `{ ${head}_ = try await ${called} }`;
+}
+
+/**
+ * @param {string | undefined} doc
+ * @param {string} indent
+ */
+function docLines(doc, indent) {
+  return doc ? doc.split('\n').map((line) => `${indent}/// ${line}`.trimEnd()) : [];
+}
+
+const SHARED = `// MARK: - The screen and its navigation
+
+/// What a native screen gets: its props, which render the screen again when they change, and the navigation from it.
+final class NativeScreen<Props>: ObservableObject {
+  @Published private(set) var props: Props
+  /// The commands of the navigation from this screen.
+  let navigation: ScreenNavigation
+  let context: NativeScreenContext
+
+  init(_ context: NativeScreenContext, props decode: @escaping (NativeScreenContext) -> Props) {
+    self.context = context
+    navigation = ScreenNavigation(context: context)
+    props = decode(context)
+    context.onPropsChange = { [weak self] _ in
+      guard let self else { return }
+      self.props = decode(self.context)
+    }
+  }
+}
+
+/// The commands of the navigation from a native screen. They run in JS, as \`useNavigation()\` of a React screen does.
+struct ScreenNavigation {
+  let context: NativeScreenContext
+
+  /// Shows a screen over this one in its stack; returns the id of the screen shown.
+  @discardableResult
+  func push(_ screen: String, props: [String: Any] = [:]) async throws -> String {
+    try await context.navigate("push", arguments: [screen, ["props": props]]) as? String ?? ""
+  }
+
+  /// Shows a screen over everything, in a stack of its own.
+  @discardableResult
+  func showModal(_ screen: String, props: [String: Any] = [:]) async throws -> String {
+    try await context.navigate("showModal", arguments: [screen, ["props": props]]) as? String ?? ""
+  }
+
+  /// Shows a screen over everything, without taking the place of any.
+  @discardableResult
+  func showOverlay(_ screen: String, props: [String: Any] = [:]) async throws -> String {
+    try await context.navigate("showOverlay", arguments: [screen, ["props": props]]) as? String ?? ""
+  }
+
+  /// Shows a screen in a column of the split view this screen is in.
+  @discardableResult
+  func showInColumn(_ screen: String, props: [String: Any] = [:]) async throws -> String {
+    try await context.navigate("showInColumn", arguments: [screen, ["props": props]]) as? String ?? ""
+  }
+
+  /// Goes back to the screen before this one in its stack.
+  func pop() async throws { _ = try await context.navigate("pop", arguments: []) }
+
+  /// Goes back to a screen of this stack, by its id.
+  func popTo(_ screenId: String) async throws { _ = try await context.navigate("popTo", arguments: [screenId]) }
+
+  /// Goes back to the first screen of this stack.
+  func popToRoot() async throws { _ = try await context.navigate("popToRoot", arguments: []) }
+
+  /// Closes the modal or the overlay this screen is in.
+  func dismiss() async throws { _ = try await context.navigate("dismiss", arguments: []) }
+
+  /// Changes the options of this screen.
+  func setOptions(_ options: [String: Any]) async throws {
+    _ = try await context.navigate("setOptions", arguments: [options])
+  }
+
+  /// Selects a tab of the tabs this screen is in, by its index.
+  func selectTab(_ index: Int) async throws { _ = try await context.navigate("selectTab", arguments: [index]) }
+
+  /// Selects a tab of the tabs this screen is in, by its id.
+  func selectTab(_ id: String) async throws { _ = try await context.navigate("selectTab", arguments: [id]) }
+
+  /// The badge of this screen's tab; nil takes it away.
+  func setTabBadge(_ badge: String?) async throws {
+    _ = try await context.navigate("setTabBadge", arguments: [badge ?? NSNull()])
+  }
+}
+
+// MARK: - Plain data from JS
+
+private func isPresent(_ value: Any?) -> Bool { value != nil && !(value is NSNull) }
+private func decodeString(_ value: Any?) -> String { value as? String ?? "" }
+private func decodeNumber(_ value: Any?) -> Double { (value as? NSNumber)?.doubleValue ?? 0 }
+private func decodeInt(_ value: Any?) -> Int { (value as? NSNumber)?.intValue ?? 0 }
+private func decodeBool(_ value: Any?) -> Bool { (value as? NSNumber)?.boolValue ?? false }
+private func decodeArray<Element>(_ value: Any?, _ element: (Any?) -> Element) -> [Element] {
+  (value as? [Any])?.map(element) ?? []
+}
+`;
+
+module.exports = { swiftFile };

package/cli/config.js

@@ -0,0 +1,78 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** @typedef {'swiftui' | 'uikit'} IosKind */
+/** @typedef {'compose' | 'views'} AndroidKind */
+/**
+ * The CLI's settings, under `"apexNavigation"` in the app's package.json:
+ * - screensDir: where `screen` puts new screens, from the app's root;
+ * - nativeScreens: what each native screen is made with on each platform, by its native name; codegen creates the
+ *   screens from it;
+ * - splash: what `splash` makes the native splash from;
+ * - icons: what `icons` makes the app icon from.
+ * @typedef {{
+ *   screensDir?: string;
+ *   nativeScreens?: Record<string, { ios?: IosKind; android?: AndroidKind }>;
+ *   splash?: import('./splash/settings').SplashSettings;
+ *   icons?: Partial<{ logo: string; image: string; background: string; darkLogo: string; logoSize: number }>;
+ * }} Config
+ */
+
+const KEY = 'apexNavigation';
+
+/**
+ * @param {string} root
+ * @returns {Config}
+ */
+function readConfig(root) {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))[KEY];
+    return typeof config === 'object' && config !== null ? config : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Where new screens go: the folder of the settings, else `src/screens` (or `screens` in an app without `src`).
+ * @param {string} root
+ * @param {Config} config
+ */
+function screensDir(root, config) {
+  if (config.screensDir) return config.screensDir;
+  return fs.existsSync(path.join(root, 'src')) ? 'src/screens' : 'screens';
+}
+
+/**
+ * The change of package.json that stores the settings `update` makes; `done` when they are there already. The file
+ * keeps its indentation.
+ * @param {string} root
+ * @param {(config: Config) => Config} update
+ * @returns {import('./changes').FileChange}
+ */
+function configChange(root, update) {
+  const file = path.join(root, 'package.json');
+  const before = fs.readFileSync(file, 'utf8');
+  const json = JSON.parse(before);
+  const current = json[KEY] ?? {};
+  const next = update(current);
+  if (JSON.stringify(next) === JSON.stringify(current)) {
+    return { name: 'package.json', platform: 'js', file, status: 'done', note: 'settings kept' };
+  }
+  json[KEY] = next;
+  const indent = /^([ \t]+)"/m.exec(before)?.[1] ?? '  ';
+  return {
+    name: 'package.json',
+    platform: 'js',
+    file,
+    status: 'change',
+    before,
+    next: JSON.stringify(json, null, indent) + '\n',
+    note: `"${KEY}" settings`,
+  };
+}
+
+module.exports = { readConfig, screensDir, configChange };

package/cli/diff.js

@@ -0,0 +1,139 @@
+// @ts-check
+'use strict';
+
+/**
+ * @typedef {{ type: ' ' | '-' | '+'; text: string }} DiffLine
+ */
+
+/**
+ * The lines of `after` against those of `before`: kept, removed and added, in order (longest common subsequence;
+ * the files this compares are a few dozen lines).
+ * @param {string} before
+ * @param {string} after
+ * @returns {DiffLine[]}
+ */
+function diffLines(before, after) {
+  const a = linesOf(before);
+  const b = linesOf(after);
+  // common[i][j]: the length of the longest common subsequence of a[i..] and b[j..].
+  const common = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      common[i][j] =
+        a[i] === b[j] ? common[i + 1][j + 1] + 1 : Math.max(common[i + 1][j], common[i][j + 1]);
+    }
+  }
+  /** @type {DiffLine[]} */
+  const lines = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      lines.push({ type: ' ', text: a[i] });
+      i++;
+      j++;
+    } else if (common[i + 1][j] >= common[i][j + 1]) {
+      lines.push({ type: '-', text: a[i++] });
+    } else {
+      lines.push({ type: '+', text: b[j++] });
+    }
+  }
+  while (i < a.length) lines.push({ type: '-', text: a[i++] });
+  while (j < b.length) lines.push({ type: '+', text: b[j++] });
+  return lines;
+}
+
+/**
+ * The changed lines with `context` kept lines around them; `null` marks the lines left out between two groups.
+ * @param {DiffLine[]} lines
+ * @param {number} [context]
+ * @returns {(DiffLine | null)[]}
+ */
+function hunks(lines, context = 2) {
+  const keep = lines.map(() => false);
+  lines.forEach((line, index) => {
+    if (line.type === ' ') return;
+    for (
+      let k = Math.max(0, index - context);
+      k <= Math.min(lines.length - 1, index + context);
+      k++
+    )
+      keep[k] = true;
+  });
+  /** @type {(DiffLine | null)[]} */
+  const shown = [];
+  lines.forEach((line, index) => {
+    if (keep[index]) shown.push(line);
+    else if (shown.length > 0 && shown[shown.length - 1] !== null) shown.push(null);
+  });
+  if (shown[shown.length - 1] === null) shown.pop();
+  return shown;
+}
+
+/**
+ * A unified diff of a file, as git prints it, for tools and AI agents (`--json`): `context` kept lines around each group
+ * of changes, with the line numbers of both texts. Empty when nothing changed.
+ * @param {string} name the file's path, for the headers
+ * @param {string} before empty for a new file
+ * @param {string} after
+ * @param {number} [context]
+ * @returns {string}
+ */
+function unifiedDiff(name, before, after, context = 3) {
+  // Each line with its number in the old and in the new text.
+  let oldLine = 1;
+  let newLine = 1;
+  const lines = diffLines(before, after).map((line) => {
+    const numbered = { ...line, old: oldLine, new: newLine };
+    if (line.type !== '+') oldLine++;
+    if (line.type !== '-') newLine++;
+    return numbered;
+  });
+  const changed = lines.flatMap((line, index) => (line.type === ' ' ? [] : [index]));
+  if (changed.length === 0) return '';
+  /** @type {[number, number][]} */
+  const groups = [];
+  const around = (/** @type {number} */ index) =>
+    /** @type {[number, number]} */ ([
+      Math.max(0, index - context),
+      Math.min(lines.length - 1, index + context),
+    ]);
+  let [start, end] = around(changed[0]);
+  for (const index of changed.slice(1)) {
+    const [from, to] = around(index);
+    if (from <= end + 1) {
+      end = to;
+    } else {
+      groups.push([start, end]);
+      [start, end] = [from, to];
+    }
+  }
+  groups.push([start, end]);
+  // A new file comes from nothing, a removed one goes to nothing.
+  const out = [
+    before === '' ? '--- /dev/null' : `--- a/${name}`,
+    after === '' ? '+++ /dev/null' : `+++ b/${name}`,
+  ];
+  for (const [from, to] of groups) {
+    const group = lines.slice(from, to + 1);
+    const inOld = group.filter((line) => line.type !== '+');
+    const inNew = group.filter((line) => line.type !== '-');
+    // An empty side starts at the line before, as git writes it.
+    const oldStart = inOld.length > 0 ? inOld[0].old : group[0].old - 1;
+    const newStart = inNew.length > 0 ? inNew[0].new : group[0].new - 1;
+    out.push(`@@ -${oldStart},${inOld.length} +${newStart},${inNew.length} @@`);
+    for (const line of group) out.push(`${line.type}${line.text}`);
+  }
+  return out.join('\n') + '\n';
+}
+
+/**
+ * The lines of a text without the empty one after its last line break; none in an empty text, so a new file is
+ * added whole.
+ * @param {string} text
+ */
+function linesOf(text) {
+  return text === '' ? [] : text.replace(/\n$/, '').split('\n');
+}
+
+module.exports = { diffLines, hunks, unifiedDiff };