@bacons/apple-targets 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 evanbacon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+# Apple Targets plugin
+
+<img width="1061" alt="Screenshot 2023-06-10 at 1 59 26 PM" src="https://github.com/EvanBacon/expo-apple-targets/assets/9664363/4cd8399d-53aa-401a-9caa-3a1432a0640c">
+
+An experimental Expo Config Plugin that generates native Apple Targets like Widgets or App Clips, and links them outside the `/ios` directory. You can open Xcode and develop the targets inside the virtual `expo:targets` folder and the changes will be saved outside of the `ios` directory. This pattern enables building things that fall outside of the scope of React Native while still obtaining all the benefits of Continuous Native Generation.
+
+> This is highly experimental and not part of any official Expo workflow.
+
+## 🚀 How to use
+
+- Add targets to `targets/` directory with an `expo-target.config.json` file.
+- Currently, if you don't have an `Info.plist`, it'll be generated on `npx expo prebuild`. This may be changed in the future so if you have an `Info.plist` it'll be used, otherwise, it'll be generated.
+- Any files in a top-level `target/*/assets` directory will be linked as resources of the target. This was added to support Safari Extensions.
+- A single top-level `*.entitlements` file will be linked as the entitlements of the target. This is not currently used in EAS Capability signing, but may be in the future.
+- All top-level swift files will be linked as build sources of the target. There is currently no support for storyboard or `.xib` files because I can't be bothered.
+- All top-level `*.xcassets` will be linked as resources, and accessible in the targets. If you add files outside of Xcode, you'll need to re-run `npx expo prebuild` to link them.
+- Code-signing requires the teamId be provided to the plugin in `app.config.js`.
+
+```json
+{
+  "plugins": [
+    [
+      "@bacons/apple-targets",
+      {
+        "teamId": "XXXXXXXXXX"
+      }
+    ]
+  ]
+}
+```
+
+You can change the root directory from `./targets` to something else with `root: "./src/targets"`. Avoid doing this.
+
+## Using React Native in Targets
+
+I'm not sure, that's not the purpose of this plugin. I built this so I could easily build iOS widgets and other minor targets with SwiftUI. I imagine it would be straightforward to use React Native in share, notification, iMessage, Safari, and photo editing extensions, you can build that on top of this plugin if you want.
+
+## `expo-target.config.json`
+
+This file can have the following properties:
+
+```json
+{
+  "type": "widget",
+
+  // Name of the target/product. Defaults to the directory name.
+  "name": "My Widget",
+
+  // Generates colorset files for the target.
+  "colors": {
+    // or "$accent": "red",
+    "$accent": { "color": "red", "darkColor": "blue" }
+  },
+  "icon": "../assets/icon.png",
+  // Can also be a URL
+  "frameworks": [
+    // Frameworks without the extension, these will be added to the target.
+    "SwiftUI"
+  ],
+  "entitlements": {
+    // Serialized entitlements. Useful for configuring with environment variables.
+  },
+  // Generates xcassets for the target.
+  "images": {
+    "thing": "../assets/thing.png"
+  },
+
+  // The iOS version fot the target.
+  "deploymentTarget": "13.4"
+}
+```
+
+You can also use `.js` with the typedoc for autocomplete:
+
+```js
+/** @type {import('@bacons/apple-targets').Config} */
+module.exports = {
+  type: "watch",
+  colors: {
+    $accent: "steelblue",
+  },
+  deploymentTarget: "9.4",
+};
+```
+
+## Colors
+
+There are certain values that are shared across targets. We use a predefined convention to map these values across targets.
+
+| Name                | Build Setting                                        | Purpose                                                                                                      |
+| ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `$accent`           | `ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME`     | Sets the global accent color, in widgets this is used for the tint color of buttons when editing the widget. |
+| `$widgetBackground` | `ASSETCATALOG_COMPILER_WIDGET_BACKGROUND_COLOR_NAME` | Sets the background color of the widget.                                                                     |
+
+## Examples
+
+### `widget`
+
+> I wrote a blog about this one and used it in production. Learn more: [Expo x Apple Widgets](https://evanbacon.dev/blog/apple-home-screen-widgets).
+
+```js
+/** @type {import('@bacons/apple-targets').Config} */
+module.exports = {
+  type: "widget",
+  icon: "../../icons/widget.png",
+  colors: {
+    // This color is referenced in the Info.plist
+    $widgetBackground: "#DB739C",
+
+    $accent: "#F09458",
+
+    // Optional: Add colors that can be used in SwiftUI.
+    gradient1: {
+      light: "#E4975D",
+      dark: "#3E72A0",
+    },
+  },
+  // Optional: Add images that can be used in SwiftUI.
+  images: {
+    valleys: "../../valleys.png",
+  },
+  // Optional: Add entitlements to the target, this one can be used to share data between the widget and the app.
+  entitlements: {
+    "com.apple.security.application-groups": ["group.bacon.data"],
+  },
+};
+```
+
+### `action`
+
+These show up in the share sheet. The icon should be transparent as it will be masked by the system.
+
+```js
+/** @type {import('@bacons/apple-targets').Config} */
+module.exports = {
+  type: "action",
+  name: "Inspect Element",
+  icon: "./assets/icon.png",
+  colors: {
+    TouchBarBezel: "#DB739C",
+  },
+};
+```
+
+Add a JavaScript file to `assets/index.js`:
+
+```js
+class Action {
+  /**
+   * `extensionName: "com.bacon.2095.axun"`
+   * @param {*} arguments: {completionFunction: () => unknown; extensionName: string; }
+   */
+  run({ extensionName, completionFunction }) {
+    // Here, you can run code that modifies the document and/or prepares
+    // things to pass to your action's native code.
+
+    // We will not modify anything, but will pass the body's background
+    // style to the native code.
+    completionFunction({
+      /* */
+    });
+  }
+
+  finalize() {
+    // Runs after the native action code has completed.
+  }
+}
+
+window.ExtensionPreprocessingJS = new Action();
+```
+
+Ensure `NSExtensionJavaScriptPreprocessingFile: "index"` in the Info.plist.
+
+### `spotlight`
+
+Populate the Spotlight search results with your app's content.
+
+```js
+/** @type {import('@bacons/apple-targets').Config} */
+module.exports = {
+  type: "spotlight",
+};
+```
+
+### Supported types
+
+Ideally, this would be generated automatically based on a fully qualified Xcode project, but for now it's a manual process. The currently supported types are based on static analysis of the most commonly used targets in the iOS App Store. I haven't tested all of these and they may not work.
+
+| Type                 | Description                        |
+| -------------------- | ---------------------------------- |
+| action               | Share Action                       |
+| widget               | Widget / Live Activity             |
+| watch                | Watch App (with companion iOS App) |
+| clip                 | App Clip                           |
+| safari               | Safari Extension                   |
+| share                | Share Extension                    |
+| notification-content | Notification Content Extension     |
+| notification-service | Notification Service Extension     |
+| intent               | Siri Intent Extension              |
+| intent-ui            | Siri Intent UI Extension           |
+| spotlight            | Spotlight Index Extension          |
+| bg-download          | Background Download Extension      |
+| quicklook-thumbnail  | Quick Look Thumbnail Extension     |
+| location-push        | Location Push Service Extension    |
+| credentials-provider | Credentials Provider Extension     |
+| account-auth         | Account Authentication Extension   |
+
+<!-- | imessage             | iMessage Extension               | -->
+
+## Code Signing
+
+The codesigning is theoretically handled entirely by [EAS Build](https://docs.expo.dev/build/introduction/). This plugin will add the requisite entitlements for target signing to work. I've only tested this end-to-end with my Pillar Valley Widget.
+
+You can also manually sign all sub-targets if you want, I'll light a candle for you.
+
+## Xcode parsing
+
+This plugin makes use of my proprietary Xcode parsing library, [`@bacons/xcode`](https://github.com/evanbacon/xcode). It's mostly typed, very untested, and possibly full of bugs––however, it's still 10x nicer than the alternative.

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require('./build')

package/build/colorset/customColorFromCSS.d.ts

@@ -0,0 +1,10 @@
+export declare function customColorFromCSS(color: string): {
+    /** @example `0.86584504117670746` */
+    red: number;
+    /** @example `0.26445041990630447` */
+    green: number;
+    /** @example `0.3248577810203549` */
+    blue: number;
+    /** @example `1` */
+    alpha: number;
+};

package/build/colorset/customColorFromCSS.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.customColorFromCSS = void 0;
+// @ts-expect-error
+const normalize_color_1 = __importDefault(require("@react-native/normalize-color"));
+function customColorFromCSS(color) {
+    let colorInt = (0, normalize_color_1.default)(color);
+    colorInt = ((colorInt << 24) | (colorInt >>> 8)) >>> 0;
+    const red = ((colorInt >> 16) & 255) / 255;
+    const green = ((colorInt >> 8) & 255) / 255;
+    const blue = (colorInt & 255) / 255;
+    const alpha = ((colorInt >> 24) & 255) / 255;
+    return {
+        red,
+        green,
+        blue,
+        alpha,
+    };
+}
+exports.customColorFromCSS = customColorFromCSS;

package/build/colorset/withIosColorset.d.ts

@@ -0,0 +1,11 @@
+import { ConfigPlugin } from "@expo/config-plugins";
+export declare const withIosColorset: ConfigPlugin<{
+    cwd: string;
+    name: string;
+    color: string;
+    darkColor?: string;
+}>;
+export declare function setColorAsync({ color, darkColor }: {
+    color: string;
+    darkColor?: string;
+}, colorsetFilePath: string): Promise<void>;

package/build/colorset/withIosColorset.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setColorAsync = exports.withIosColorset = void 0;
+const config_plugins_1 = require("@expo/config-plugins");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const customColorFromCSS_1 = require("./customColorFromCSS");
+const withIosColorset = (config, { cwd, color, darkColor, name }) => {
+    return (0, config_plugins_1.withDangerousMod)(config, [
+        "ios",
+        async (config) => {
+            await setColorAsync({ color, darkColor }, node_path_1.default.join(config.modRequest.projectRoot, cwd, `Assets.xcassets/${name}.colorset`));
+            return config;
+        },
+    ]);
+};
+exports.withIosColorset = withIosColorset;
+const DARK_APPEARANCE = {
+    appearance: "luminosity",
+    value: "dark",
+};
+function createColor(color) {
+    return {
+        "color-space": "srgb",
+        components: (0, customColorFromCSS_1.customColorFromCSS)(color),
+    };
+}
+async function setColorAsync({ color, darkColor }, colorsetFilePath) {
+    // Ensure the Images.xcassets/AppIcon.appiconset path exists
+    await node_fs_1.default.promises.mkdir(colorsetFilePath, { recursive: true });
+    // Store the image JSON data for assigning via the Contents.json
+    const colorsJson = [];
+    if (color) {
+        colorsJson.push({
+            color: createColor(color),
+            idiom: "universal",
+        });
+    }
+    if (darkColor) {
+        colorsJson.push({
+            appearances: [DARK_APPEARANCE],
+            color: createColor(darkColor),
+            idiom: "universal",
+        });
+    }
+    // Finally, write the Config.json
+    await writeContentsJsonAsync(colorsetFilePath, {
+        colors: colorsJson,
+    });
+}
+exports.setColorAsync = setColorAsync;
+async function writeContentsJsonAsync(directory, { colors }) {
+    await node_fs_1.default.promises.mkdir(directory, { recursive: true });
+    await node_fs_1.default.promises.writeFile(node_path_1.default.join(directory, "Contents.json"), JSON.stringify({
+        colors,
+        info: {
+            version: 1,
+            // common practice is for the tool that generated the icons to be the "author"
+            author: "expo",
+        },
+    }, null, 2));
+}

package/build/config.d.ts

@@ -0,0 +1,103 @@
+import { ExtensionType } from "./target";
+export type DynamicColor = {
+    light: string;
+    dark?: string;
+};
+export type Entitlements = Partial<{
+    "com.apple.developer.healthkit": boolean;
+    "com.apple.developer.healthkit.access": string[];
+    /** prefixed with `merchant.` */
+    "com.apple.developer.in-app-payments": string[];
+    /** prefixed with `iCloud.` */
+    "com.apple.developer.icloud-container-identifiers": string[];
+    "com.apple.developer.ClassKit-environment": "production" | "development";
+    "com.apple.developer.default-data-protection": "NSFileProtectionCompleteUnlessOpen" | "NSFileProtectionCompleteUntilFirstUserAuthentication" | "NSFileProtectionNone" | "NSFileProtectionComplete";
+    "com.apple.developer.networking.networkextension": ("dns-proxy" | "app-proxy-provider" | "content-filter-provider" | "packet-tunnel-provider" | "dns-proxy-systemextension" | "app-proxy-provider-systemextension" | "content-filter-provider-systemextension" | "packet-tunnel-provider-systemextension" | "dns-settings" | "app-push-provider")[];
+    "com.apple.developer.networking.vpn.api": "allow-vpn"[];
+    "com.apple.developer.networking.HotspotConfiguration": boolean;
+    "com.apple.developer.kernel.extended-virtual-addressing": boolean;
+    "com.apple.developer.homekit": boolean;
+    "com.apple.developer.networking.multipath": boolean;
+    "com.apple.external-accessory.wireless-configuration": boolean;
+    "inter-app-audio": boolean;
+    "com.apple.developer.pass-type-identifiers": "$(TeamIdentifierPrefix)*"[];
+    "com.apple.developer.user-fonts": ("app-usage" | "system-installation")[];
+    "com.apple.developer.devicecheck.appattest-environment": "development" | "production";
+    "com.apple.developer.nfc.readersession.formats": ("NDEF" | "TAG")[];
+    "com.apple.developer.applesignin": "Default"[];
+    "com.apple.developer.siri": boolean;
+    "com.apple.developer.networking.wifi-info": boolean;
+    "com.apple.developer.usernotifications.communication": boolean;
+    "com.apple.developer.usernotifications.time-sensitive": boolean;
+    "com.apple.developer.group-session": boolean;
+    "com.apple.developer.family-controls": boolean;
+    "com.apple.developer.authentication-services.autofill-credential-provider": boolean;
+    "com.apple.developer.game-center": boolean;
+    /** prefixed with `group.` */
+    "com.apple.security.application-groups": string[];
+    "com.apple.developer.fileprovider.testing-mode": boolean;
+    "com.apple.developer.healthkit.recalibrate-estimates": boolean;
+    "com.apple.developer.maps": boolean;
+    "com.apple.developer.user-management": boolean;
+    "com.apple.developer.networking.custom-protocol": boolean;
+    "com.apple.developer.system-extension.install": boolean;
+    "com.apple.developer.push-to-talk": boolean;
+    "com.apple.developer.driverkit.transport.usb": boolean;
+    "com.apple.developer.kernel.increased-memory-limit": boolean;
+    "com.apple.developer.driverkit.communicates-with-drivers": boolean;
+    "com.apple.developer.media-device-discovery-extension": boolean;
+    "com.apple.developer.driverkit.allow-third-party-userclients": boolean;
+    "com.apple.developer.weatherkit": boolean;
+    "com.apple.developer.on-demand-install-capable": boolean;
+    "com.apple.developer.driverkit.family.scsicontroller": boolean;
+    "com.apple.developer.driverkit.family.serial": boolean;
+    "com.apple.developer.driverkit.family.networking": boolean;
+    "com.apple.developer.driverkit.family.hid.eventservice": boolean;
+    "com.apple.developer.driverkit.family.hid.device": boolean;
+    "com.apple.developer.driverkit": boolean;
+    "com.apple.developer.driverkit.transport.hid": boolean;
+    "com.apple.developer.driverkit.family.audio": boolean;
+    "com.apple.developer.shared-with-you": boolean;
+}>;
+export type Config = {
+    /**
+     * The type of extension to generate.
+     * @example "widget"
+     */
+    type: ExtensionType;
+    /** Name of the target. Will default to a sanitized version of the directory name. */
+    name?: string;
+    /**
+     * A local file path or URL to an image asset.
+     * @example "./assets/icon.png"
+     * @example "https://example.com/icon.png"
+     */
+    icon?: string;
+    /**
+     * A list of additional frameworks to add to the target.
+     * @example ["UserNotifications", "Intents"]
+     */
+    frameworks?: string[];
+    /** Deployment iOS version for the target. Defaults to `16.4` */
+    deploymentTarget?: string;
+    /** Apple team ID to use for signing the target. Defaults to whatever is used in the main App target. */
+    appleTeamId?: string;
+    /** Optional entitlements to add to the target. */
+    entitlements?: Entitlements;
+    /**
+     * Additional colors to generate in the `Assets.xcassets`. These will be available as `UIColor`s in the native source.
+     * @example In Expo config: `colors: { gradient1: { color: "#FF0000", darkColor: "#0000FF" }`
+     * @example In Swift: `Color("gradient1")` -> `#FF0000` in light-mode
+     */
+    colors?: Record<string, string | DynamicColor>;
+    /**
+     * Additional images to generate in the `Assets.xcassets`. These will be available as `UIImage`s in the native source. The sources can be URLs or local file paths.
+     * @example In Expo config: `images: { evan: "https://github.com/evanbacon.png" }`
+     * @example In Swift: `Image("evan")` -> `[picture of guy]`
+     */
+    images?: Record<string, string | {
+        "1x"?: string;
+        "2x"?: string;
+        "3x"?: string;
+    }>;
+};

package/build/config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/icon/withImageAsset.d.ts

@@ -0,0 +1,26 @@
+import { ConfigPlugin } from "@expo/config-plugins";
+import { ContentsJsonImageIdiom, ContentsJsonImage } from "@expo/prebuild-config/build/plugins/icons/AssetContents";
+export declare const withImageAsset: ConfigPlugin<{
+    cwd: string;
+    name: string;
+    image: string | {
+        "1x"?: string;
+        "2x"?: string;
+        "3x"?: string;
+    };
+}>;
+export declare const ICON_CONTENTS: {
+    idiom: ContentsJsonImageIdiom;
+    sizes: {
+        size: number;
+        scales: (1 | 2 | 3)[];
+    }[];
+}[];
+export declare function setIconsAsync(icon: string, projectRoot: string, iosNamedProjectRoot: string, cacheComponent: string): Promise<void>;
+export declare function generateResizedImageAsync(icon: {
+    "1x"?: string;
+    "2x"?: string;
+    "3x"?: string;
+} | string, name: string, projectRoot: string, iosNamedProjectRoot: string, cacheComponent: string): Promise<ContentsJsonImage[]>;
+export declare function generateIconsInternalAsync(icon: string, projectRoot: string, iosNamedProjectRoot: string, cacheComponent: string): Promise<ContentsJsonImage[]>;
+export declare function generateWatchIconsInternalAsync(icon: string, projectRoot: string, iosNamedProjectRoot: string, cacheComponent: string): Promise<ContentsJsonImage[]>;