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

package/cli/icons/images.js

@@ -0,0 +1,202 @@
+// @ts-check
+'use strict';
+
+const path = require('node:path');
+
+/** @typedef {import('./settings').IconSettings} IconSettings */
+
+/**
+ * The images of the app icon:
+ * - iOS, 1024 px: `light` the icon, no transparency; `dark` and `tinted` the logo on a transparent background, in
+ *   color and in gray (none for a ready icon: iOS makes them);
+ * - Android, per density: the adaptive icon's `foreground` (108 dp) and `monochrome` layers (none for a ready icon),
+ *   and the icons of Android 7 and older, square and round (48 dp).
+ * `logo` is the logo's size in dp in the adaptive icon, for the check of its safe circle.
+ * @typedef {{
+ *   ios: { light: Buffer; dark?: Buffer; tinted?: Buffer };
+ *   android: { density: string; foreground: Buffer; monochrome?: Buffer; legacy: Buffer; round: Buffer }[];
+ *   logo?: { width: number; height: number };
+ * }} IconImages
+ */
+
+/** @typedef {(root: string, settings: IconSettings) => Promise<IconImages>} MakeIcons */
+
+const IOS_SIZE = 1024;
+// The adaptive icon's layers, the part of them the mask shows, and the icons before Android 8, in dp.
+const LAYER = 108;
+const VIEWPORT = 72;
+const LEGACY = 48;
+const DENSITIES = /** @type {const} */ ([
+  ['mdpi', 1],
+  ['hdpi', 1.5],
+  ['xhdpi', 2],
+  ['xxhdpi', 3],
+  ['xxxhdpi', 4],
+]);
+// An SVG is drawn at the size it goes to, up to this density: sharp draws it at 72 dpi otherwise, and scales that up.
+const MAX_SVG_DENSITY = 2400;
+
+/**
+ * Makes the images with sharp. Throws when an image can't be read.
+ * @param {any} sharp
+ * @returns {MakeIcons}
+ */
+function iconMaker(sharp) {
+  return async (root, settings) => {
+    const background = settings.background;
+    if ('image' in settings) {
+      const image = path.resolve(root, settings.image);
+      return {
+        ios: { light: await flatten(sharp, await fitted(sharp, image, IOS_SIZE), background) },
+        android: await Promise.all(
+          DENSITIES.map(async ([density, factor]) => {
+            const legacy = await fitted(sharp, image, Math.round(LEGACY * factor));
+            return {
+              density,
+              foreground: await onSquare(
+                sharp,
+                Math.round(LAYER * factor),
+                await fitted(sharp, image, Math.round(VIEWPORT * factor))
+              ),
+              legacy,
+              round: await circle(sharp, legacy),
+            };
+          })
+        ),
+      };
+    }
+
+    const logo = path.resolve(root, settings.logo);
+    const darkLogo = settings.darkLogo ? path.resolve(root, settings.darkLogo) : logo;
+    const share = settings.logoSize / 100;
+    const iosLogo = Math.round(IOS_SIZE * share);
+    const darkIos = await fitted(sharp, darkLogo, iosLogo);
+    const { width = 1, height = 1 } = await sharp(await fitted(sharp, logo, 1000)).metadata();
+    const box = VIEWPORT * share;
+    return {
+      ios: {
+        light: await flatten(
+          sharp,
+          await onSquare(sharp, IOS_SIZE, await fitted(sharp, logo, iosLogo)),
+          background
+        ),
+        dark: await onSquare(sharp, IOS_SIZE, darkIos),
+        tinted: await onSquare(
+          sharp,
+          IOS_SIZE,
+          await sharp(darkIos).modulate({ saturation: 0 }).png().toBuffer()
+        ),
+      },
+      android: await Promise.all(
+        DENSITIES.map(async ([density, factor]) => {
+          const layerLogo = await fitted(sharp, logo, Math.round(box * factor));
+          const legacyLogo = await fitted(sharp, logo, Math.round(LEGACY * share * factor));
+          const legacy = await flatten(
+            sharp,
+            await onSquare(sharp, Math.round(LEGACY * factor), legacyLogo),
+            background
+          );
+          return {
+            density,
+            foreground: await onSquare(sharp, Math.round(LAYER * factor), layerLogo),
+            monochrome: await onSquare(
+              sharp,
+              Math.round(LAYER * factor),
+              await silhouette(sharp, layerLogo)
+            ),
+            legacy,
+            round: await circle(sharp, legacy),
+          };
+        })
+      ),
+      logo:
+        width >= height
+          ? { width: box, height: (box * height) / width }
+          : { width: (box * width) / height, height: box },
+    };
+  };
+}
+
+/**
+ * The image as a PNG that fits a square of `size` pixels, its proportions kept.
+ * @param {any} sharp
+ * @param {string} file
+ * @param {number} size
+ * @returns {Promise<Buffer>}
+ */
+async function fitted(sharp, file, size) {
+  const metadata = await sharp(file).metadata();
+  const density =
+    metadata.format === 'svg'
+      ? Math.min(
+          MAX_SVG_DENSITY,
+          Math.max(72, (72 * size) / Math.max(metadata.width, metadata.height))
+        )
+      : undefined;
+  return sharp(file, density ? { density } : {})
+    .resize({ width: size, height: size, fit: 'inside' })
+    .png()
+    .toBuffer();
+}
+
+/**
+ * The image in the middle of a transparent square, `size` pixels a side.
+ * @param {any} sharp
+ * @param {Buffer} image
+ * @param {number} size
+ * @returns {Promise<Buffer>}
+ */
+function onSquare(sharp, size, image) {
+  return sharp({
+    create: { width: size, height: size, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } },
+  })
+    .composite([{ input: image, gravity: 'center' }])
+    .png()
+    .toBuffer();
+}
+
+/**
+ * The image on the color, with no transparency left: the App Store refuses an icon with an alpha channel.
+ * @param {any} sharp
+ * @param {Buffer} image
+ * @param {string} color `#RRGGBB`
+ * @returns {Promise<Buffer>}
+ */
+function flatten(sharp, image, color) {
+  return sharp(image).flatten({ background: color }).removeAlpha().png().toBuffer();
+}
+
+/**
+ * The shape of the image in white, its transparency kept: the layer Android tints with the colors of the theme.
+ * @param {any} sharp
+ * @param {Buffer} image
+ * @returns {Promise<Buffer>}
+ */
+async function silhouette(sharp, image) {
+  const { width, height } = await sharp(image).metadata();
+  const alpha = await sharp(image).ensureAlpha().extractChannel(3).toBuffer();
+  return sharp({ create: { width, height, channels: 3, background: '#FFFFFF' } })
+    .joinChannel(alpha)
+    .png()
+    .toBuffer();
+}
+
+/**
+ * The image cut to the circle it fills.
+ * @param {any} sharp
+ * @param {Buffer} image
+ * @returns {Promise<Buffer>}
+ */
+async function circle(sharp, image) {
+  const { width } = await sharp(image).metadata();
+  const mask = Buffer.from(
+    `<svg width="${width}" height="${width}"><circle cx="${width / 2}" cy="${width / 2}" r="${width / 2}" fill="#fff"/></svg>`
+  );
+  return sharp(image)
+    .ensureAlpha()
+    .composite([{ input: mask, blend: 'dest-in' }])
+    .png()
+    .toBuffer();
+}
+
+module.exports = { iconMaker, DENSITIES };

package/cli/icons/index.js

@@ -0,0 +1,97 @@
+// @ts-check
+'use strict';
+
+const { createRun } = require('../changes');
+const { configChange, readConfig } = require('../config');
+const { exec, execInTerminal } = require('../exec');
+const { requireSharp, sharpInstallCommand } = require('../images');
+const { findProject } = require('../project');
+const { createUI } = require('../ui');
+const { planAndroidIcons } = require('./android');
+const { iconMaker } = require('./images');
+const { planIosIcons } = require('./ios');
+const { iconsHash, resolveIconSettings } = require('./settings');
+
+/** @typedef {import('./settings').IconOptions} IconOptions */
+/** @typedef {import('./images').MakeIcons} MakeIcons */
+
+// The safe zone of Android's adaptive icon: a circle of this diameter in dp, which no mask cuts.
+const SAFE_CIRCLE = 66;
+
+/**
+ * Makes the app icon of both platforms from a logo and a color, or from a ready square icon: the iOS icon set (one
+ * size, dark and tinted), the Android adaptive and themed icons and those of Android 7. The settings go into
+ * package.json, so a run without options makes the icon again from them. The images are made with sharp, which the
+ * command offers to add to the app's dev dependencies.
+ * @param {{
+ *   root: string;
+ *   options: IconOptions;
+ *   yes: boolean;
+ *   dryRun: boolean;
+ *   json?: boolean;
+ *   ui?: ReturnType<typeof createUI>;
+ *   run?: import('../exec').Exec;
+ *   install?: (manager: string, args: string[]) => boolean;
+ *   makeIcons?: MakeIcons;
+ * }} options `install` runs the package manager, `makeIcons` makes the images (both replaced in tests)
+ * @returns {Promise<number>} the exit code
+ */
+async function icons({
+  root,
+  options,
+  yes,
+  dryRun,
+  json = false,
+  ui = createUI(),
+  run = exec,
+  install = (manager, args) => execInTerminal(manager, args, { cwd: root }),
+  makeIcons,
+}) {
+  const command = createRun({ command: 'icons', root, json, ui });
+  if (!json) ui.banner({ command: 'icons', facts: [{ text: 'iOS · Android' }] });
+
+  const resolved = resolveIconSettings(root, options, readConfig(root).icons);
+  if ('errors' in resolved) return command.fail('icons-settings', resolved.errors);
+  const { settings } = resolved;
+
+  if (!makeIcons) {
+    const sharp = await requireSharp(root, { yes, dryRun, json, ui, install, what: 'The icons' });
+    if (!sharp) {
+      return command.fail(
+        'sharp-missing',
+        `The icons command makes its images with sharp: ${sharpInstallCommand(root).join(' ')}, then run it again.`
+      );
+    }
+    makeIcons = iconMaker(sharp);
+  }
+  let images;
+  try {
+    images = await makeIcons(root, settings);
+  } catch (error) {
+    return command.fail('icons-image', error instanceof Error ? error.message : String(error));
+  }
+  if (images.logo && Math.hypot(images.logo.width, images.logo.height) > SAFE_CIRCLE) {
+    command.warn(
+      `The logo's corners leave the safe circle of Android's icon (${SAFE_CIRCLE} dp): a round mask may cut them. Make --logo-size smaller.`
+    );
+  }
+
+  const hash = iconsHash(root, settings);
+  const project = findProject(root, run);
+  return command.apply(
+    [
+      ...planIosIcons(project, images, hash),
+      ...planAndroidIcons(project, images, settings.background, hash),
+      configChange(root, (current) => ({ ...current, icons: settings })),
+    ],
+    {
+      yes,
+      dryRun,
+      done: 'The icons are made: build the app again to see them.',
+      nothingToDo: 'The icons are made already.',
+      next: ['npx react-native run-ios · run-android'],
+    }
+  );
+}
+
+module.exports = { icons };

package/cli/icons/ios.js

@@ -0,0 +1,113 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { projectInfoPlist } = require('../links/identity');
+const { madeFile, oldFile } = require('../splash/files');
+const { buildSetting } = require('../xcode/pbxproj');
+
+/** @typedef {import('../changes').FileChange} FileChange */
+/** @typedef {import('./images').IconImages} IconImages */
+
+/** The author of an icon set the command made, with the hash of what it was made from after it. */
+const AUTHOR = 'apex-navigation icons';
+
+/**
+ * The icon set of the iOS app: the one the target names (`AppIcon` in the template), in the app's asset catalog.
+ * @param {import('../project').Project} project
+ * @returns {string | undefined}
+ */
+function iconSetDir(project) {
+  if (!project.infoPlist) return undefined;
+  const pbxproj =
+    project.xcodeProject && fs.existsSync(project.xcodeProject)
+      ? fs.readFileSync(project.xcodeProject, 'utf8')
+      : '';
+  const infoPlist = projectInfoPlist(project);
+  const name =
+    (infoPlist &&
+      buildSetting(pbxproj, infoPlist, 'ASSETCATALOG_COMPILER_APPICON_NAME').find(Boolean)) ??
+    'AppIcon';
+  return path.join(path.dirname(project.infoPlist), 'Images.xcassets', `${name}.appiconset`);
+}
+
+/**
+ * The iOS icon set made anew: one 1024 px image for iPhone and iPad (Xcode makes the other sizes), with its dark and
+ * tinted versions; the files of the set before go.
+ * @param {import('../project').Project} project
+ * @param {IconImages} images
+ * @param {string} hash
+ * @returns {FileChange[]}
+ */
+function planIosIcons(project, images, hash) {
+  const dir = iconSetDir(project);
+  if (!dir) return [];
+  const entry = (/** @type {string} */ filename, /** @type {string | undefined} */ appearance) => ({
+    ...(appearance && { appearances: [{ appearance: 'luminosity', value: appearance }] }),
+    filename,
+    idiom: 'universal',
+    platform: 'ios',
+    size: '1024x1024',
+  });
+  const files = [
+    { name: 'AppIcon.png', image: images.ios.light, note: 'the icon, 1024 px' },
+    ...(images.ios.dark
+      ? [{ name: 'AppIcon-Dark.png', image: images.ios.dark, note: 'dark', appearance: 'dark' }]
+      : []),
+    ...(images.ios.tinted
+      ? [
+          {
+            name: 'AppIcon-Tinted.png',
+            image: images.ios.tinted,
+            note: 'tinted',
+            appearance: 'tinted',
+          },
+        ]
+      : []),
+  ];
+  const contents = {
+    images: files.map(({ name, appearance }) => entry(name, appearance)),
+    info: { author: `${AUTHOR} ${hash}`, version: 1 },
+  };
+  const kept = new Set(['Contents.json', ...files.map(({ name }) => name)]);
+  const old = fs.existsSync(dir)
+    ? fs
+        .readdirSync(dir)
+        .filter((name) => !kept.has(name))
+        .map((name) => oldFile('ios', path.join(dir, name)))
+    : [];
+  return [
+    ...files.map(({ name, image, note }) => madeFile('ios', path.join(dir, name), image, note)),
+    madeFile(
+      'ios',
+      path.join(dir, 'Contents.json'),
+      JSON.stringify(contents, null, 2) + '\n',
+      'one size for iPhone and iPad'
+    ),
+    ...old.map((change) => ({ ...change, note: 'an older icon' })),
+  ];
+}
+
+/**
+ * The hash in the iOS icon set the command made; undefined for a set made otherwise.
+ * @param {import('../project').Project} project
+ * @returns {{ hash?: string; images: number } | undefined} `images`: how many entries of the set have a file
+ */
+function readIconSet(project) {
+  const dir = iconSetDir(project);
+  const file = dir && path.join(dir, 'Contents.json');
+  if (!file || !fs.existsSync(file)) return undefined;
+  try {
+    const contents = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const author = String(contents.info?.author ?? '');
+    return {
+      hash: author.startsWith(AUTHOR) ? author.slice(AUTHOR.length).trim() : undefined,
+      images: (contents.images ?? []).filter((/** @type {any} */ image) => image.filename).length,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+module.exports = { planIosIcons, readIconSet, iconSetDir };

package/cli/icons/settings.js

@@ -0,0 +1,116 @@
+// @ts-check
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { normalizeColor } = require('../splash/settings');
+
+/**
+ * What the app icon is made from, under `apexNavigation.icons` in the app's package.json, paths from the app's root:
+ * - from a logo: the logo (PNG, JPEG, WebP or SVG on a transparent background), the color behind it, a logo for the
+ *   dark appearance, and the logo's width in percent of the visible icon (iOS: the whole icon; Android: the 72 dp of
+ *   the adaptive icon the mask shows);
+ * - from a ready square icon: the image, and the color that fills its transparent parts.
+ * @typedef {{ logo: string; background: string; darkLogo?: string; logoSize: number }
+ *   | { image: string; background: string }} IconSettings
+ */
+
+/**
+ * The options of `icons`, as the command line gives them.
+ * @typedef {{ logo?: string; image?: string; background?: string; darkLogo?: string; logoSize?: string }} IconOptions
+ */
+
+const DEFAULT_BACKGROUND = '#FFFFFF';
+const DEFAULT_LOGO_SIZE = 60;
+const IMAGE = /\.(png|jpe?g|webp|svg)$/i;
+// Changes when the files the command makes change, so that doctor asks for them again after an update of the CLI.
+const FORMAT = 1;
+
+/**
+ * The settings: the options over the saved ones of the same kind (a logo or an image), or what is wrong with them.
+ * @param {string} root
+ * @param {IconOptions} options
+ * @param {Partial<{ logo: string; image: string; background: string; darkLogo: string; logoSize: number }>} [saved]
+ * @returns {{ settings: IconSettings } | { errors: string[] }}
+ */
+function resolveIconSettings(root, options, saved = {}) {
+  /** @type {string[]} */
+  const errors = [];
+  if (options.logo && options.image) {
+    return { errors: ['--logo and --image make the icon two ways: give one of them'] };
+  }
+  const fromImage = options.image !== undefined || (!options.logo && saved.image !== undefined);
+  // Settings of the other kind don't carry over: a logo's dark logo means nothing to an image.
+  const kept = fromImage === (saved.image !== undefined) ? saved : {};
+  const background = normalizeColor(options.background ?? kept.background ?? DEFAULT_BACKGROUND);
+  if (background === null || background === undefined) {
+    errors.push('--background is a color such as #FFFFFF');
+  }
+
+  if (fromImage) {
+    const image = options.image ?? kept.image;
+    checkFile(root, '--image', image, errors);
+    if (errors.length > 0 || !image || !background) return { errors };
+    return { settings: { image: relative(root, image), background } };
+  }
+
+  const logo = options.logo ?? kept.logo;
+  const darkLogo = options.darkLogo ?? kept.darkLogo;
+  const logoSize = Number(options.logoSize ?? kept.logoSize ?? DEFAULT_LOGO_SIZE);
+  if (!logo)
+    errors.push('The icon needs a logo, --logo assets/logo.png, or a ready icon, --image icon.png');
+  checkFile(root, '--logo', logo, errors);
+  checkFile(root, '--dark-logo', darkLogo, errors);
+  if (!Number.isFinite(logoSize) || logoSize < 20 || logoSize > 100) {
+    errors.push('--logo-size is a percent of the icon from 20 to 100');
+  }
+  if (errors.length > 0 || !logo || !background) return { errors };
+  return {
+    settings: {
+      logo: relative(root, logo),
+      background,
+      ...(darkLogo && { darkLogo: relative(root, darkLogo) }),
+      logoSize,
+    },
+  };
+}
+
+/**
+ * A short hash of what the icon is made from: the settings and the bytes of the images, not where they are. The
+ * files the command makes carry it, and doctor compares.
+ * @param {string} root
+ * @param {IconSettings} settings
+ */
+function iconsHash(root, settings) {
+  const hash = crypto.createHash('sha256');
+  const files = 'image' in settings ? [settings.image] : [settings.logo, settings.darkLogo];
+  const { background } = settings;
+  const logoSize = 'logoSize' in settings ? settings.logoSize : undefined;
+  hash.update(JSON.stringify({ FORMAT, background, logoSize, image: 'image' in settings }));
+  for (const file of files) if (file) hash.update(fs.readFileSync(path.resolve(root, file)));
+  return hash.digest('hex').slice(0, 8);
+}
+
+/**
+ * @param {string} root
+ * @param {string} flag
+ * @param {string | undefined} file
+ * @param {string[]} errors
+ */
+function checkFile(root, flag, file, errors) {
+  if (!file) return;
+  if (!IMAGE.test(file)) errors.push(`${flag} is a PNG, JPEG, WebP or SVG file, not ${file}`);
+  else if (!fs.existsSync(path.resolve(root, file))) errors.push(`${flag}: there is no ${file}`);
+}
+
+/**
+ * A path from the app's root, with forward slashes, as package.json keeps it.
+ * @param {string} root
+ * @param {string} file
+ */
+function relative(root, file) {
+  return path.relative(root, path.resolve(root, file)).split(path.sep).join('/');
+}
+
+module.exports = { resolveIconSettings, iconsHash };

package/cli/images.js

@@ -0,0 +1,67 @@
+// @ts-check
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { exec } = require('./exec');
+
+// Adding sharp downloads its binary: up to minutes.
+const LONG = 20 * 60_000;
+
+/**
+ * sharp from the app's packages; undefined when the app doesn't have it. The commands that make images (`splash`,
+ * `icons`) load it from the app, so the navigation itself doesn't depend on it.
+ * @param {string} root
+ * @returns {any}
+ */
+function loadSharp(root) {
+  try {
+    return require(require.resolve('sharp', { paths: [root] }));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * sharp, added to the app's dev dependencies after asking when the app doesn't have it; undefined when it isn't there.
+ * A dry run and `--json` without `--yes` don't install.
+ * @param {string} root
+ * @param {{
+ *   yes: boolean;
+ *   dryRun: boolean;
+ *   json: boolean;
+ *   ui: import('./ui').UI;
+ *   install: (manager: string, args: string[]) => boolean;
+ *   what: string;
+ * }} options `what` names the images in the question, such as `The splash images`
+ * @returns {Promise<any>}
+ */
+async function requireSharp(root, { yes, dryRun, json, ui, install, what }) {
+  const sharp = loadSharp(root);
+  if (sharp || dryRun || (json && !yes)) return sharp;
+  const [manager, ...args] = sharpInstallCommand(root);
+  const confirmed =
+    yes || (await ui.confirm(`${what} are made with sharp. Add it to the dev dependencies?`));
+  if (!confirmed) return undefined;
+  // Under --json the output is one document: the package manager prints into the result's pipe, not the terminal.
+  const installed = json
+    ? exec(manager, args, { cwd: root, timeout: LONG }).ok
+    : install(manager, args);
+  if (!installed) return undefined;
+  return loadSharp(root);
+}
+
+/**
+ * The command that adds sharp to the app's dev dependencies, with the package manager of its lockfile.
+ * @param {string} root
+ * @returns {string[]}
+ */
+function sharpInstallCommand(root) {
+  const has = (/** @type {string} */ name) => fs.existsSync(path.join(root, name));
+  if (has('yarn.lock')) return ['yarn', 'add', '--dev', 'sharp'];
+  if (has('bun.lock') || has('bun.lockb')) return ['bun', 'add', '--dev', 'sharp'];
+  if (has('pnpm-lock.yaml')) return ['pnpm', 'add', '--save-dev', 'sharp'];
+  return ['npm', 'install', '--save-dev', 'sharp'];
+}
+
+module.exports = { loadSharp, requireSharp, sharpInstallCommand };