@forgebook/react-native-web 0.0.0-stage → 0.2.0

package/dist/src/vite/projectPostcss.js

@@ -0,0 +1,122 @@
+/**
+ * The project's PostCSS configuration run on its style sheets, as Expo does for the web: Tailwind's, which NativeWind's
+ * classes come from, among them.
+ *
+ * @remarks
+ * Forgebook compiles style sheets with Lightning CSS, which runs no PostCSS. A React Native project that styles with
+ * NativeWind has a `postcss.config` naming Tailwind, and Expo runs it on the web: so does this plugin, before Lightning
+ * CSS, on the style sheets of a project that has one. Without a configuration it does nothing and loads nothing;
+ * `postcss` is an optional peer, which a project with a configuration has.
+ *
+ * Tailwind reads the project's files for the classes they use, and says so in its result (`dir-dependency`): an edit
+ * to one of those files on the dev server compiles the style sheet again, so a new class has its rule.
+ *
+ * @module
+ */
+import { relative } from "node:path";
+import { isForgebookFile } from "./forgebookFiles.js";
+/** A style sheet PostCSS runs on: not one imported as text or as an address. */
+const STYLE_SHEET = /\.css(?:$|\?)/;
+/** A style sheet's imports that are not compiled. */
+const NOT_COMPILED = /[?&](?:raw|url)\b/;
+/**
+ * The folders a PostCSS result depends on, from its messages.
+ *
+ * @param messages - the result's messages.
+ * @returns each folder, and each file, a result names.
+ */
+export const dependenciesOf = (messages) => {
+    const dirs = [];
+    const files = [];
+    for (const message of messages) {
+        if (typeof message !== "object" || message === null || !("type" in message))
+            continue;
+        if (message.type === "dir-dependency" && "dir" in message && typeof message.dir === "string")
+            dirs.push({ dir: message.dir });
+        if (message.type === "dependency" && "file" in message && typeof message.file === "string")
+            files.push(message.file);
+    }
+    return { dirs, files };
+};
+/**
+ * The project's PostCSS, loaded from its configuration.
+ *
+ * @param root - the project's folder.
+ * @returns it, or none when the project has no PostCSS configuration.
+ */
+const loadPostcss = async (root) => {
+    const { default: postcssrc } = await import("postcss-load-config");
+    let loaded;
+    try {
+        loaded = await postcssrc({}, root);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith("No PostCSS Config found"))
+            return undefined;
+        throw error;
+    }
+    const { default: postcss } = await import("postcss");
+    const runner = postcss(loaded.plugins);
+    return {
+        process: async (css, from) => {
+            const result = await runner.process(css, { ...loaded.options, from, to: from });
+            return { css: result.css, messages: result.messages };
+        }
+    };
+};
+/**
+ * Whether a file is in a folder.
+ *
+ * @param file - the file, absolute.
+ * @param dir - the folder, absolute.
+ */
+const isInside = (file, dir) => {
+    const path = relative(dir, file);
+    return path !== "" && !path.startsWith("..") && !path.startsWith("/");
+};
+/** The plugin. */
+export const projectPostcss = () => {
+    let root = ".";
+    let postcss;
+    // the style sheets compiled with folders they depend on, by file
+    const watched = new Map();
+    return {
+        name: "forgebook:react-native-web-postcss",
+        enforce: "pre",
+        configResolved: (config) => {
+            root = config.root;
+        },
+        transform: {
+            filter: { id: STYLE_SHEET },
+            async handler(code, id) {
+                const file = id.split("?", 1)[0] ?? id;
+                if (NOT_COMPILED.test(id) || file.includes("/node_modules/") || isForgebookFile(file))
+                    return null;
+                // a configuration that failed to load is read again with the next style sheet, once it is mended
+                postcss ??= loadPostcss(root).catch((error) => {
+                    postcss = undefined;
+                    throw error;
+                });
+                const project = await postcss;
+                if (project === undefined)
+                    return null;
+                const result = await project.process(code, file);
+                const { dirs, files } = dependenciesOf(result.messages);
+                for (const dependency of files)
+                    this.addWatchFile(dependency);
+                if (dirs.length > 0)
+                    watched.set(file, dirs);
+                return { code: result.css, map: null };
+            }
+        },
+        // a file Tailwind reads for its classes changed: its style sheets are compiled again with the page's next request
+        handleHotUpdate: ({ file, server, modules }) => {
+            const sheets = [...watched]
+                .filter(([sheet, dirs]) => sheet !== file && dirs.some((each) => isInside(file, each.dir)))
+                .flatMap(([sheet]) => [...(server.moduleGraph.getModulesByFile(sheet) ?? [])]);
+            for (const sheet of sheets)
+                server.moduleGraph.invalidateModule(sheet);
+            return sheets.length === 0 ? undefined : [...modules, ...sheets];
+        }
+    };
+};

package/dist/src/vite/reactNativeWeb.d.ts

@@ -0,0 +1,53 @@
+import type { FrameworkAdapter } from "forgebook/vite/adapter";
+/** Which files an option applies to: a path pattern, a regular expression, or a list of them. */
+export type FilePattern = string | RegExp | readonly (string | RegExp)[];
+/** A Babel plugin or preset, by its module's name, with its options when it takes some: as a Babel configuration writes it. */
+export type BabelItem = string | readonly [name: string, options: Readonly<Record<string, unknown>>];
+/** The Babel plugins and presets a catalogue runs, as a project's `babel.config.js` names them for Metro. */
+export type BabelOptions = {
+    /** The plugins (`"react-native-worklets/plugin"` for Reanimated 4, `"react-native-reanimated/plugin"` for 3). */
+    readonly plugins?: readonly BabelItem[];
+    /**
+     * The presets. NativeWind needs none: its JSX runtime (`jsxImportSource`) is enough, and its Babel preset compiles
+     * JSX itself and adds Reanimated's plugin a second time.
+     */
+    readonly presets?: readonly BabelItem[];
+};
+/** The options of `reactNativeWeb()`: Storybook's React Native Web framework's, under the names Forgebook gives them. */
+export type ReactNativeWebOptions = {
+    /**
+     * The packages written for React Native, by name, besides those of React Native's and Expo's families
+     * (`react-native-*`, `@react-native/*`, `expo-*`, `@expo/*`), which always are: a package that imports `react-native`
+     * or ships code as Metro reads it (JSX in `.js` files, Flow types). Their code is compiled as Metro compiles it, and
+     * their `react-native` is react-native-web on the dev server's Node side too, where the agents' answers read the
+     * stories. None by default; Storybook calls them `modulesToTranspile`.
+     */
+    readonly nativePackages?: readonly string[];
+    /**
+     * The module JSX is compiled against, for every file the catalogue compiles: `"nativewind"` for NativeWind, whose
+     * runtime turns a `className` into styles. React's (`"react"`) by default.
+     */
+    readonly jsxImportSource?: string;
+    /**
+     * The Babel plugins and presets run on the files `include` names (the project's own scripts by default), after
+     * Vite has resolved them: Reanimated's worklets plugin, NativeWind's preset. They need `@babel/core` and
+     * `@rolldown/plugin-babel` installed; without this option, no Babel runs. Storybook's
+     * `pluginReactOptions.babel`.
+     */
+    readonly babel?: BabelOptions;
+    /**
+     * The files React's plugin (Fast Refresh) and Babel apply to; every script outside `node_modules` by default.
+     * Storybook's `pluginReactOptions.include`.
+     */
+    readonly include?: FilePattern;
+    /** The files React's plugin and Babel leave alone; `node_modules` by default. Storybook's `pluginReactOptions.exclude`. */
+    readonly exclude?: FilePattern;
+};
+/**
+ * React Native in the browser, through react-native-web, as the plugin reads and draws its components.
+ *
+ * @param options - the other packages written for React Native, the JSX import source, Babel's plugins and presets.
+ * @returns the adapter.
+ * @throws when `jsxImportSource` is not a package's name.
+ */
+export declare const reactNativeWeb: (options?: ReactNativeWebOptions) => FrameworkAdapter;

package/dist/src/vite/reactNativeWeb.js

@@ -0,0 +1,65 @@
+/**
+ * Forgebook's adapter for React Native, for the Vite plugin: `defineConfig({ framework: reactNativeWeb() })`.
+ *
+ * @remarks
+ * A React Native component is a React component drawn with React Native's primitives: in the browser, react-native-web
+ * draws them with the DOM. So the props are read as React's, and the stories drawn with React's renderer inside a root
+ * that lays out as React Native's does (`@forgebook/react-native-web/frame`). What React Native adds is Vite's work:
+ * the plugins of `nativePlugin.ts`, the project's PostCSS (`projectPostcss.ts`), and the Babel plugins and presets the
+ * catalogue names (Reanimated's, NativeWind's), run by `@rolldown/plugin-babel`. A project's Metro and Babel
+ * configuration files are not read: the catalogue names what it needs, as Storybook's React Native Web framework does.
+ *
+ * @module
+ */
+import { extname } from "node:path";
+import { react } from "@forgebook/react/vite";
+import { babelPlugins } from "./babelPlugins.js";
+import { nativePlugins } from "./nativePlugin.js";
+import { projectPostcss } from "./projectPostcss.js";
+/** A package's name, scoped or not, as npm allows it. */
+const PACKAGE_NAME = /^(?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/;
+/**
+ * React's Vite plugin (Fast Refresh) on the catalogue's files. The JSX import source is not its: it would reach
+ * Forgebook's own pages too, so `nativePlugin.ts` names it in the project's files.
+ *
+ * @param options - the adapter's options.
+ */
+const reactPlugin = async (options) => {
+    const { default: plugin } = await import("@vitejs/plugin-react");
+    return plugin({
+        ...(options.include === undefined ? {} : { include: [options.include].flat() }),
+        ...(options.exclude === undefined ? {} : { exclude: [options.exclude].flat() })
+    });
+};
+/**
+ * React Native in the browser, through react-native-web, as the plugin reads and draws its components.
+ *
+ * @param options - the other packages written for React Native, the JSX import source, Babel's plugins and presets.
+ * @returns the adapter.
+ * @throws when `jsxImportSource` is not a package's name.
+ */
+export const reactNativeWeb = (options = {}) => {
+    // it is written into a comment of every project file and imported by name: a package's name, nothing else
+    if (options.jsxImportSource !== undefined && !PACKAGE_NAME.test(options.jsxImportSource))
+        throw new Error(`reactNativeWeb({ jsxImportSource }) takes a package's name: ${options.jsxImportSource} is not one`);
+    const base = react();
+    return {
+        name: "react-native-web",
+        // beside this module, with its extension: `.ts` in the sources, `.js` once built for npm
+        docsModule: new URL(`./extractDocs${extname(import.meta.url)}`, import.meta.url).href,
+        pages: { frame: "@forgebook/react-native-web/frame", code: base.pages.code },
+        browserDependencies: [
+            ...(base.browserDependencies ?? []),
+            "react-native-web",
+            ...(options.jsxImportSource === undefined
+                ? []
+                : [`${options.jsxImportSource}/jsx-runtime`, `${options.jsxImportSource}/jsx-dev-runtime`])
+        ],
+        vitePlugins: async () => [
+            ...nativePlugins(options),
+            projectPostcss(),
+            ...(await babelPlugins(options)),
+            await reactPlugin(options)
+        ]
+    };
+};

package/package.json

@@ -1,6 +1,110 @@
 {
   "name": "@forgebook/react-native-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Forgebook for React Native: a React Native project's components drawn in the browser through react-native-web, on Vite, their props read as React's.",
+  "keywords": [
+    "react-native",
+    "react-native-web",
+    "expo",
+    "react",
+    "catalogue",
+    "stories"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ensiria/forgebook.git",
+    "directory": "packages/react-native-web"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/src/stories.d.ts",
+      "default": "./dist/src/stories.js"
+    },
+    "./docs": {
+      "types": "./dist/src/vite/extractDocs.d.ts",
+      "default": "./dist/src/vite/extractDocs.js"
+    },
+    "./frame": {
+      "types": "./dist/src/mountFrame.d.ts",
+      "default": "./dist/src/mountFrame.js"
+    },
+    "./frame-renderer": {
+      "types": "./dist/src/nativeFrameRenderer.d.ts",
+      "default": "./dist/src/nativeFrameRenderer.js"
+    },
+    "./renderer": {
+      "types": "./dist/src/nativeRenderer.d.ts",
+      "default": "./dist/src/nativeRenderer.js"
+    },
+    "./vite": {
+      "types": "./dist/src/vite/reactNativeWeb.d.ts",
+      "default": "./dist/src/vite/reactNativeWeb.js"
+    }
+  },
+  "dependencies": {
+    "@vitejs/plugin-react": "6.1.2",
+    "flow-remove-types": "2.338.0",
+    "postcss-load-config": "6.0.1",
+    "@forgebook/react": "0.2.0"
+  },
+  "peerDependencies": {
+    "@babel/core": "^7.29.0",
+    "@rolldown/plugin-babel": "^0.2.4",
+    "postcss": "^8.4.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0",
+    "react-native": ">=0.76.0 <1.0.0",
+    "react-native-web": "^0.21.0",
+    "vite": "^8.0.0",
+    "forgebook": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@babel/core": {
+      "optional": true
+    },
+    "@rolldown/plugin-babel": {
+      "optional": true
+    },
+    "postcss": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@babel/core": "7.29.7",
+    "@rolldown/plugin-babel": "0.2.4",
+    "@types/node": "24.19.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "happy-dom": "21.0.4",
+    "postcss": "8.5.32",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "react-native": "0.88.1",
+    "react-native-web": "0.21.4",
+    "vite": "8.3.5",
+    "vitest": "5.0.5",
+    "@forgebook/story-format": "0.2.0",
+    "@forgebook/typescript-config": "0.0.0",
+    "@forgebook/testing": "0.2.0",
+    "@forgebook/tools": "0.0.0",
+    "forgebook": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "package-build build",
+    "manifest": "package-build manifest",
+    "test": "vitest run",
+    "typecheck": "tsc -p src && tsc -p src/vite && tsc -p test"
+  }
 }