basalt-core 0.0.0-rc5

package/dist/metro-config.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Metro configuration for this project's desktop platforms.
+ *
+ * An out-of-tree React Native platform has to do two things to Metro, and the
+ * second is the one that is not obvious.
+ *
+ * First, the platform has to be one Metro knows about, so that
+ * `Button.macos.js` wins over `Button.js` the way `Button.android.js` would.
+ *
+ * Second, some of React Native's own modules cannot work on a platform it has
+ * never heard of. There are three kinds, and each needs different handling:
+ *
+ *   1. **Self-importing shims.** React Native ships a family of files whose
+ *      entire body is `import X from './X'; export default X;`, each marked
+ *      with a note about "backwards compatibility of subpath (deep) imports".
+ *      They exist so `react-native/Libraries/Image/Image` keeps working, and
+ *      they rely on a platform-specific sibling winning the resolution. Bundle
+ *      for one of these platforms and each resolves to *itself*, exports
+ *      undefined, and kills whatever touches it -- as `Platform.constants`
+ *      being undefined, or a view config being undefined, or a component being
+ *      undefined.
+ *
+ *   2. **Modules with no neutral fallback at all**, which do not resolve, so
+ *      there is no resolution to rewrite -- only a failure to intercept.
+ *
+ *   3. **Modules this project genuinely implements differently**, which is
+ *      `Platform` and `TextInput`.
+ *
+ * React Native for Windows solves all of this with a whole override system and
+ * a fork of every file it replaces. This is the same idea at the smallest size
+ * that works.
+ *
+ * None of the three kinds is Linux-specific, which is the point of this file's
+ * shape: the answers are identical for linux, macos and windows, and only
+ * `Platform` differs, by one string. Anything that has to be written per
+ * platform is a `.linux.js` / `.macos.js` / `.windows.js` file in
+ * `src/overrides`, and the tables below name it.
+ *
+ * Usage, in an app's metro.config.js:
+ *
+ *     const {withDesktopPlatforms} = require('basalt-core/metro-config');
+ *     module.exports = withDesktopPlatforms(config);
+ *
+ * @format
+ */
+/**
+ * Metro's resolver types, as far as this file uses them.
+ *
+ * Metro ships no usable types for `resolveRequest` and its context, and the
+ * shape is large. What is described here is exactly what this file reads and
+ * calls, which is the same rule the turbo modules and Metro's build API got.
+ */
+export type Resolution = {
+    filePath: string;
+    type?: string;
+};
+export type ResolutionContext = {
+    resolveRequest: (context: ResolutionContext, moduleName: string, platform: string | null) => Resolution;
+    originModulePath?: string;
+    [key: string]: unknown;
+};
+export type ResolveRequest = (context: ResolutionContext, moduleName: string, platform: string | null) => Resolution;
+/**
+ * A Metro config, as far as this composes with one. Deliberately loose: an app
+ * hands in whatever `getDefaultConfig` produced, and claiming to know the rest
+ * of that object would be claiming to know Metro's config schema.
+ */
+export type MetroConfig = {
+    resolver?: {
+        platforms?: string[];
+        nodeModulesPaths?: string[];
+        resolveRequest?: ResolveRequest;
+        [key: string]: unknown;
+    };
+    server?: {
+        rewriteRequestUrl?: (url: string) => string;
+        [key: string]: unknown;
+    };
+    projectRoot?: string;
+    watchFolders?: string[];
+    [key: string]: unknown;
+};
+export type DesktopPlatformOptions = {
+    /** Which desktops to enable. Defaults to all three. */
+    platforms?: string[];
+    /** Which one a dev-server request with no `app=` is assumed to be. */
+    devServerPlatform?: string;
+    /** What to fall back to for a module with no desktop implementation. */
+    platformFallbacks?: string[];
+};
+/**
+ * One entry in an override table: the tail of a path React Native would have
+ * resolved, and what to use instead -- either a fixed path or one chosen by
+ * the platform being bundled for.
+ */
+type OverrideEntry = [string, string | ((platform: string) => string)];
+/**
+ * The platforms this package can bundle for.
+ *
+ * `macos` and `windows` deliberately match the names react-native-macos and
+ * react-native-windows use. A library that ships `Button.macos.js` for those
+ * forks resolves correctly here without knowing this project exists, and a
+ * library that does not is no worse off. Picking different names would have
+ * bought nothing and cost that.
+ */
+export declare const DESKTOP_PLATFORMS: string[];
+/**
+ * Kind 1: React Native's self-importing deep-import shims.
+ *
+ * Each is answered with its own `.android.js` sibling rather than a file of
+ * ours. That is deliberate: these platforms report `PlatformConstantsAndroid`
+ * from C++, share ReactCommon's prop parsing, and drive the same components
+ * Android's JavaScript drives, so Android's implementation is the one that
+ * matches what is actually implemented here. Copying them would mean nine forks
+ * drifting silently from upstream.
+ *
+ * Found with:
+ *
+ *     grep -rl 'backwards compatibility of subpath (deep) imports' Libraries src
+ *
+ * Spelled out rather than detected, so a new shim upstream produces an honest
+ * failure here rather than a silent redirect to Android.
+ */
+export declare const SELF_IMPORTING_SHIMS: string[];
+/**
+ * Kind 3: modules this project implements itself. Checked before the shim list,
+ * so `Platform` gets ours rather than Android's.
+ *
+ * A replacement is either a path, when every platform shares it, or a function
+ * of the platform when they do not. Only `Platform` needs the second form, and
+ * the one-line files it points at exist so that the difference between the
+ * platforms stays exactly one string. See src/overrides/createPlatform.js.
+ */
+export declare const PLATFORM_OVERRIDES: ReadonlyArray<OverrideEntry>;
+/**
+ * Kind 2: modules React Native ships only as `.android.js` and `.ios.js`, with
+ * no neutral file to resolve to. Keyed without an extension, because a request
+ * that fails to resolve is only known by its extensionless path.
+ */
+export declare const MISSING_MODULES: ReadonlyArray<OverrideEntry>;
+/**
+ * How a host tells the dev server which desktop it is.
+ *
+ * ReactCxxPlatform's DevServerHelper builds its bundle URL from
+ * `constexpr DEFAULT_PLATFORM = "android"`, with no hook and no setting, so
+ * every desktop host asks Metro for an android bundle. Left alone, an app would
+ * be `Platform.OS === 'android'` under Fast Refresh and its real value in a
+ * release build, which is a far worse trap than either on its own.
+ *
+ * The request is therefore corrected on arrival, and the only thing in it that
+ * a host controls is `app=`, which comes from `ReactInstanceConfig::appId` and
+ * which Metro itself ignores. So the hosts set that to
+ * `basalt-<platform>` and this reads it back.
+ *
+ * It is a workaround and it should not have to exist. The fix is a `platform`
+ * field on ReactInstanceConfig, upstream.
+ */
+export declare const APP_ID_PREFIX = "basalt-";
+export declare function appIdFor(platform: string): string;
+export declare function withDesktopPlatforms(config?: MetroConfig, options?: DesktopPlatformOptions): MetroConfig;
+/**
+ * The original name, kept working. Enables only `linux`, which is what it
+ * always did, so an app that has this in its metro.config.js keeps the exact
+ * behaviour it had.
+ */
+export declare function withLinuxPlatform(config?: MetroConfig): MetroConfig;
+export {};
+//# sourceMappingURL=metro-config.d.ts.map

package/dist/metro-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metro-config.d.ts","sourceRoot":"","sources":["../metro-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAKH;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC;AAE3D,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,CACd,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,KACpB,UAAU,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,CAC3B,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,KACpB,UAAU,CAAC;AAEhB;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,MAAM,CAAC,EAAE;QACP,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;QAC5C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B,CAAC;AAEF;;;;GAIG;AACH,KAAK,aAAa,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC;AAIvE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,UAAgC,CAAC;AAE/D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,UAUhC,CAAC;AA+CF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,aAAa,CAiF3D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,aAAa,CAAC,aAAa,CAKxD,CAAC;AA4BF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjD;AA+ID,wBAAgB,oBAAoB,CAClC,MAAM,GAAE,WAAgB,EACxB,OAAO,GAAE,sBAA2B,GACnC,WAAW,CA0Pb;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,WAAgB,GAAG,WAAW,CAEvE"}