basalt-navigation 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vince Vella
+
+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

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# basalt-navigation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Native screens for react-navigation on the desktop.
+
+```bash
+npm install basalt-navigation
+```
+
+```jsx
+import {NavigationScreens} from 'basalt-navigation';
+
+<NavigationScreens>
+  <NavigationContainer>{/* navigators, as usual */}</NavigationContainer>
+</NavigationScreens>
+```
+
+That is the whole API. Wrap it once, as high as you like.
+
+## What it does
+
+react-navigation's native stack renders every screen it has pushed and leaves
+it to the platform to show the top one. Basalt implements the components that
+do that, and on Windows they are used already. On macOS and Linux
+react-native-screens renders plain views instead, so every pushed screen stays
+mounted: invisible, because the screen in front covers it, but still measured
+and still reachable by a screen reader.
+
+This makes those two behave like Windows.
+
+## What it is not
+
+Not a fork, not a patch, and nothing is rewritten in `node_modules`.
+react-native-screens picks the component it renders for each screen out of a
+React context:
+
+```js
+const ScreenWrapper = React.useContext(ScreenContext) || InnerScreen;
+```
+
+The platform check lives inside `InnerScreen`, so providing a different screen
+through that context is enough, and it is a public extension point rather than
+a crack. `ScreenStack` needs nothing at all: it is not gated and renders its
+native component everywhere already.
+
+## When you will not need it
+
+[react-native-screens#4779](https://github.com/software-mansion/react-native-screens/pull/4779)
+proposes letting a platform that supplies the components say so. If it lands,
+this package becomes two calls in your application and can go:
+
+```ts
+provideNativeScreens(); // basalt registers RNSScreen and the rest
+enableScreens(); // use them
+```
+
+Two calls rather than one, and that is the point of them. An earlier revision of
+that pull request reused `enableScreens()` for both, and the review was right to
+refuse it: applications call it unconditionally, and on a platform with no native
+screens it has always meant "use them where they exist" and kept the fallback.
+Reusing it would have made react-native-macos, which has no implementation there
+either, mount components that are not registered.
+
+## The one wart
+
+The screen component is taken from `react-native-screens/src/fabric/`, which
+is a path inside the library rather than part of its public API, so a release
+that moves it would break this. Declaring the component here instead was tried
+and is worse: it needs React Native's base view config, and requiring that
+pulled this package into a module cycle where react-native-screens came back
+`undefined` and the application died on a property of undefined. A path that
+can break loudly on upgrade beat a cycle that breaks confusingly at runtime.

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Native screens for react-navigation, on a desktop.
+ *
+ * ## What this is for
+ *
+ * react-navigation's native stack renders every screen it has pushed and
+ * leaves it to the platform to show the top one. Basalt implements the
+ * components that do that, `RNSScreen` and `RNSScreenStack`, and on Windows
+ * they are used: `Platform.OS` is `windows`, which react-native-screens has on
+ * its own list of platforms it ships native code for.
+ *
+ * `macos` and `linux` are not on that list, and cannot be, because
+ * react-native-macos reports `macos` too and the library has no macOS
+ * implementation behind it. So on those two the library renders plain views
+ * instead, every pushed screen stays mounted, and a screen reader can reach the
+ * one behind the one you are on.
+ *
+ * ## Why this is not a patch
+ *
+ * The gate lives inside `InnerScreen`, and `ScreenContext` is the library's own
+ * way of replacing that component:
+ *
+ *     const ScreenWrapper = React.useContext(ScreenContext) || InnerScreen;
+ *
+ * So a provider is enough. Nothing here forks the library, pins a version of
+ * it, or rewrites anything in `node_modules`; it uses a public extension point
+ * and goes out of the way the moment it is not wrapped around anything.
+ *
+ * `ScreenStack` needs nothing: it is not gated and renders its native
+ * component everywhere already. Only the screens inside it were missing.
+ *
+ * ## When this stops being necessary
+ *
+ * software-mansion/react-native-screens#4779 proposes letting a platform that
+ * supplies the components say so, with `provideNativeScreens()`. If that lands,
+ * this package becomes two calls in an application instead, and the provider can
+ * go:
+ *
+ *     provideNativeScreens();  // basalt registers RNSScreen and the rest
+ *     enableScreens();         // use them
+ *
+ * It was `enableScreens()` alone in an earlier revision of that pull request, and
+ * the review was right to refuse it: that call is unconditional in most
+ * applications and on a platform without native screens it has always meant "use
+ * them where they exist". Overloading it would have made react-native-macos,
+ * which has no implementation there either, start mounting components that are
+ * not registered.
+ *
+ * @format
+ */
+import * as React from 'react';
+type ScreenProps = {
+    active?: number;
+    activityState?: number;
+    stackPresentation?: string;
+    style?: unknown;
+    children?: React.ReactNode;
+    [key: string]: unknown;
+};
+/**
+ * A screen, rendered natively, skipping the platform check in `InnerScreen`.
+ *
+ * `activityState` is derived from `active` the way the library derives it, for
+ * the older callers that still send the boolean. Everything else is passed
+ * through: the props a desktop does not have, the iOS sheet detents and the
+ * rest, are filtered out by the view config above rather than here, so this
+ * does not have to know which ones those are.
+ */
+declare const NativeScreen: React.ForwardRefExoticComponent<Omit<ScreenProps, "ref"> & React.RefAttributes<unknown>>;
+/**
+ * Wrap a navigator in this to get native screens on every desktop.
+ *
+ *     <NavigationScreens>
+ *       <NavigationContainer>{...}</NavigationContainer>
+ *     </NavigationScreens>
+ *
+ * Harmless on Windows, where the library already renders the same components,
+ * and harmless on iOS and Android for the same reason. An application that
+ * renders this on web would be asking for components the web build does not
+ * have, which is the one place not to put it.
+ */
+export declare function NavigationScreens({ children }: {
+    children?: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** The screen component itself, for an application wiring its own provider. */
+export { NativeScreen };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAmB/B,KAAK,WAAW,GAAG;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;;;;GAQG;AACH,QAAA,MAAM,YAAY,0FASjB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,EAAC,QAAQ,EAAC,EAAE;IAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAAC,2CAkBzE;AAED,+EAA+E;AAC/E,OAAO,EAAC,YAAY,EAAC,CAAC"}

package/dist/index.js

@@ -0,0 +1,145 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeScreen = void 0;
+exports.NavigationScreens = NavigationScreens;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/**
+ * Native screens for react-navigation, on a desktop.
+ *
+ * ## What this is for
+ *
+ * react-navigation's native stack renders every screen it has pushed and
+ * leaves it to the platform to show the top one. Basalt implements the
+ * components that do that, `RNSScreen` and `RNSScreenStack`, and on Windows
+ * they are used: `Platform.OS` is `windows`, which react-native-screens has on
+ * its own list of platforms it ships native code for.
+ *
+ * `macos` and `linux` are not on that list, and cannot be, because
+ * react-native-macos reports `macos` too and the library has no macOS
+ * implementation behind it. So on those two the library renders plain views
+ * instead, every pushed screen stays mounted, and a screen reader can reach the
+ * one behind the one you are on.
+ *
+ * ## Why this is not a patch
+ *
+ * The gate lives inside `InnerScreen`, and `ScreenContext` is the library's own
+ * way of replacing that component:
+ *
+ *     const ScreenWrapper = React.useContext(ScreenContext) || InnerScreen;
+ *
+ * So a provider is enough. Nothing here forks the library, pins a version of
+ * it, or rewrites anything in `node_modules`; it uses a public extension point
+ * and goes out of the way the moment it is not wrapped around anything.
+ *
+ * `ScreenStack` needs nothing: it is not gated and renders its native
+ * component everywhere already. Only the screens inside it were missing.
+ *
+ * ## When this stops being necessary
+ *
+ * software-mansion/react-native-screens#4779 proposes letting a platform that
+ * supplies the components say so, with `provideNativeScreens()`. If that lands,
+ * this package becomes two calls in an application instead, and the provider can
+ * go:
+ *
+ *     provideNativeScreens();  // basalt registers RNSScreen and the rest
+ *     enableScreens();         // use them
+ *
+ * It was `enableScreens()` alone in an earlier revision of that pull request, and
+ * the review was right to refuse it: that call is unconditional in most
+ * applications and on a platform without native screens it has always meant "use
+ * them where they exist". Overloading it would have made react-native-macos,
+ * which has no implementation there either, start mounting components that are
+ * not registered.
+ *
+ * @format
+ */
+const React = __importStar(require("react"));
+/**
+ * `RNSScreen`, taken from the library rather than declared here.
+ *
+ * Declaring it needs a base view config, and reaching React Native's through
+ * `require` pulled this package into a module cycle: with both this and
+ * react-native-screens in one graph, whichever was mid-initialisation came
+ * back `undefined`, and the app died on a property of undefined rather than on
+ * anything that named the cause.
+ *
+ * So the component comes from the library that already registered it. It is a
+ * path into its `src/`, which is a dependency on a layout that is not ours and
+ * is the reason this package pins a minimum version rather than a range.
+ */
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const RNSScreen = require('react-native-screens/src/fabric/ScreenNativeComponent')
+    .default;
+/**
+ * A screen, rendered natively, skipping the platform check in `InnerScreen`.
+ *
+ * `activityState` is derived from `active` the way the library derives it, for
+ * the older callers that still send the boolean. Everything else is passed
+ * through: the props a desktop does not have, the iOS sheet detents and the
+ * rest, are filtered out by the view config above rather than here, so this
+ * does not have to know which ones those are.
+ */
+const NativeScreen = React.forwardRef(function NativeScreen({ active, activityState, children, ...rest }, ref) {
+    const state = activityState ?? (active !== 0 ? 2 : 0);
+    return ((0, jsx_runtime_1.jsx)(RNSScreen, { ref: ref, activityState: state, ...rest, children: children }));
+});
+exports.NativeScreen = NativeScreen;
+/**
+ * Wrap a navigator in this to get native screens on every desktop.
+ *
+ *     <NavigationScreens>
+ *       <NavigationContainer>{...}</NavigationContainer>
+ *     </NavigationScreens>
+ *
+ * Harmless on Windows, where the library already renders the same components,
+ * and harmless on iOS and Android for the same reason. An application that
+ * renders this on web would be asking for components the web build does not
+ * have, which is the one place not to put it.
+ */
+function NavigationScreens({ children }) {
+    // Resolved at render rather than at import.
+    //
+    // At module scope this came back undefined, and the app died on
+    // "Cannot read property 'ScreenContext' of undefined". Which import in the
+    // cycle is unfinished depends on the order the application happens to import
+    // things in, and that is not a thing a library should be sensitive to. The
+    // context is not needed until something renders, so it is not asked for
+    // until then.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { ScreenContext } = require('react-native-screens');
+    return ((0, jsx_runtime_1.jsx)(ScreenContext.Provider, { value: NativeScreen, children: children }));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.tsx"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+GA,8CAkBC;;AAjID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,6CAA+B;AAE/B;;;;;;;;;;;;GAYG;AACH,8DAA8D;AAC9D,MAAM,SAAS,GAAG,OAAO,CAAC,uDAAuD,CAAC;KAC/E,OAAuD,CAAC;AAW3D;;;;;;;;GAQG;AACH,MAAM,YAAY,GAAG,KAAK,CAAC,UAAU,CACnC,SAAS,YAAY,CAAC,EAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAC,EAAE,GAAG;IACnE,MAAM,KAAK,GAAG,aAAa,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,OAAO,CACL,uBAAC,SAAS,IAAC,GAAG,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,KAAM,IAAI,YAChD,QAAQ,GACC,CACb,CAAC;AACJ,CAAC,CACF,CAAC;AAmCM,oCAAY;AAjCpB;;;;;;;;;;;GAWG;AACH,SAAgB,iBAAiB,CAAC,EAAC,QAAQ,EAA+B;IACxE,4CAA4C;IAC5C,EAAE;IACF,gEAAgE;IAChE,2EAA2E;IAC3E,6EAA6E;IAC7E,2EAA2E;IAC3E,wEAAwE;IACxE,cAAc;IACd,8DAA8D;IAC9D,MAAM,EAAC,aAAa,EAAC,GAAG,OAAO,CAAC,sBAAsB,CAErD,CAAC;IACF,OAAO,CACL,uBAAC,aAAa,CAAC,QAAQ,IAAC,KAAK,EAAE,YAAqB,YACjD,QAAQ,GACc,CAC1B,CAAC;AACJ,CAAC"}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../index.tsx","../react-native-screens.d.ts"],"version":"6.0.3"}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "basalt-navigation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Native screens for react-navigation on the desktop, through react-native-screens' own ScreenContext. No patch and no fork.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vincentvella/basalt.git",
+    "directory": "packages/basalt-navigation"
+  },
+  "homepage": "https://basaltjs.dev",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "../../scripts/build_ts.sh",
+    "prepack": "../../scripts/build_ts.sh"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-screens": ">=4"
+  }
+}