[46] parallel filesystem convention example

docs/CHANGELOG.md

@@ -20,6 +20,7 @@ This log covers the [monorepo](https://en.wikipedia.org/wiki/Monorepo).
 
 - updated to `0.11.0` of [`eslint-plugin-workspaces`](https://github.com/joshuajaco/eslint-plugin-workspaces) after [addition of ESLint9 support](https://github.com/joshuajaco/eslint-plugin-workspaces/commit/af855c3a3d8069366d4446747e91828ddf7560c6)
   - update `eslint.config.mjs` to utilise flat config
+- updated `eslint` to 9.38.0
 
 ## [0.12.0] - 2025-09-30
 

examples/express/README.md

@@ -9,3 +9,13 @@ Some example applications based on an [express](https://expressjs.com/) router
 2. [config](./src/routes/config/README.md)
 
    This example shows the use of the [`react-pointcuts`](../../packages/react-pointcuts/docs/README.md), [`features`](../../packages/features/docs/README.md), [`ssr`](../../packages/ssr/docs/README.md) and [`webpack`](../../packages/webpack/docs/README.md) packages.
+
+3. [parallel-folder-convention](./src/routes/parallel-folder-convention/README.md)
+
+   This example shows the use of the [`react-pointcuts`](../../packages/react-pointcuts/docs/README.md), [`features`](../../packages/features/docs/README.md), [`ssr`](../../packages/ssr/docs/README.md) and [`webpack`](../../packages/webpack/docs/README.md) packages.
+
+   It has a bespoke filesystem convention, with parallel directory hierarchies containing arbitrary replacements and patches of various types of module, including:
+      - constants
+      - css
+      - react components
+      - [redux slices](https://redux.js.org/tutorials/essentials/part-2-app-structure#redux-slices)

examples/express/docs/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2025-10-21
+
+### Changed
+
+- added "parallel folder convention" example
+
+### Fixed
+
+- went ltd cmdr data on the contraction "I'm", converting to "I am" since the "large" example inexplicably no longer text-matched (space before apostrophe)
+
 ## [0.3.1] - 2025-10-21
 
 ### Fixed

examples/express/eslint.config.mjs

@@ -1,15 +1,43 @@
 import examplesConfig from "../eslint.config.mjs";
 import asosConfigReact from "../../peripheral/eslint-config-asosconfig/react.js";
 import asosConfigServer from "../../peripheral/eslint-config-asosconfig/server.js";
+import parser from "@typescript-eslint/parser";
+import globals from "globals";
 
 export default [
   ...[...asosConfigReact, ...asosConfigServer].map((config) => ({
-    files: ["**/*.js"],
+    files: ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"],
     ...config,
     settings: {
+      "import/resolver": {
+        typescript: {
+          alwaysTryTypes: true,
+          project: "./src/routes/parallel-folder-convention/tsconfig.json"
+        }
+      },
       react: {
         version: "detect"
       }
+    },
+    rules: {
+      ...config.rules,
+      "react/prop-types": "off",
+      "prettier/prettier": [
+        "error",
+        {
+          trailingComma: "none",
+          endOfLine: "auto"
+        }
+      ]
+    },
+    languageOptions: {
+      ...config.languageOptions,
+      parser,
+      globals: {
+        CLIENT: "readonly",
+        ...globals.browser,
+        ...globals.node
+      }
     }
   })),
   ...examplesConfig,

examples/express/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-toggle-point-express-example",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "engines": {
     "node": ">=20.6.0"
@@ -16,32 +16,38 @@
     "prelint": "npm run build-dependencies",
     "lint": "npm run lint:code && npm run lint:docs",
     "lint:fix": "npm run lint:code -- --fix && npm run lint:docs -- --fix",
-    "lint:code": "eslint src --flag unstable_config_lookup_from_file",
-    "lint:docs": "eslint *.md --flag unstable_config_lookup_from_file"
+    "lint:code": "eslint src --flag v10_config_lookup_from_file",
+    "lint:docs": "eslint *.md --flag v10_config_lookup_from_file"
   },
   "dependencies": {
-    "@asos/web-toggle-point-react-pointcuts": "file:../../packages/react-pointcuts",
     "@asos/web-toggle-point-features": "file:../../packages/features",
+    "@asos/web-toggle-point-react-pointcuts": "file:../../packages/react-pointcuts",
     "@asos/web-toggle-point-ssr": "file:../../packages/ssr",
     "@asos/web-toggle-point-webpack": "file:../../packages/webpack",
+    "@reduxjs/toolkit": "^2.8.2",
     "cross-env": "^7.0.3",
     "express": "^4.17.1",
     "http-status-codes": "^2.3.0",
     "react": ">=17",
-    "react-dom": ">=17"
+    "react-dom": ">=17",
+    "react-redux": "^9.2.0",
+    "valtio": "^2.1.5"
   },
   "devDependencies": {
     "babel-loader": "^9.2.1",
     "css-loader": "^7.1.2",
+    "enhanced-tsconfig-paths-webpack-plugin": "^0.2.3",
     "mini-css-extract-plugin": "^2.9.2",
     "path-exists-cli": "^2.0.0",
     "prop-types": "^15.7.2",
+    "source-map-loader": "^5.0.0",
     "style-loader": "^4.0.0",
+    "ts-loader": "^9.5.2",
     "webpack": "^5.38.1",
     "webpack-cli": "^4.7.2",
     "webpack-node-externals": "^3.0.0"
   },
   "peerDependencies": {
-    "@playwright/test": "^1.49.0"
+    "@playwright/test": "^1.56.0"
   }
 }

examples/express/src/index.js

@@ -1,12 +1,14 @@
 import express from "express";
 import animalsRouter from "./routes/animals/router.js";
 import configRouter from "./routes/config/router.js";
+import parallelFolderConventionRouter from "./routes/parallel-folder-convention/router.tsx";
 
 const app = express();
 const PORT = process.env.PORT;
 
 app.use("/animals", animalsRouter);
 app.use("/config", configRouter);
+app.use("/parallel-folder-convention", parallelFolderConventionRouter);
 app.get("/", (_, response) => {
   response.send(`<!DOCTYPE html>
 <html lang="en">
@@ -39,6 +41,7 @@ app.get("/", (_, response) => {
     <ul>
       <li><a href="/animals">Version header with nodeRequestScoped store</a></li>
       <li><a href="/config">.env config with ssrBackedReactContext store for initial value in browser</a></li>
+      <li><a href="/parallel-folder-convention">parallel folder convention, with varied constants, css, react & redux</a></li>
     </ul>
   </body>
 </html>`);

examples/express/src/routes/config/Component.jsx

@@ -2,7 +2,7 @@ const Component = () => (
   <div
     style={{ fontSize: "18pt", width: "50vw", minWidth: "6em", height: "50vh" }}
   >
-    I'm Medium
+    I am Medium
   </div>
 );
 

examples/express/src/routes/config/__variants__/div-style/Large/Component.jsx

@@ -8,7 +8,7 @@ const Component = ({ backgroundColor }) => (
       backgroundColor
     }}
   >
-    I'm Large
+    I am Large
   </div>
 );
 

examples/express/src/routes/config/__variants__/div-style/Small/Component.jsx

@@ -8,7 +8,7 @@ const Component = ({ backgroundColor }) => (
       backgroundColor
     }}
   >
-    I'm Small
+    I am Small
   </div>
 );
 

examples/express/src/routes/config/playwright.spec.js

@@ -14,7 +14,7 @@ test.describe("config endpoint", () => {
       });
 
       test("it shows a varied experience", async ({ page }) => {
-        await expect(page.getByText(`I'm ${size}`)).toBeInViewport();
+        await expect(page.getByText(`I am ${size}`)).toBeVisible();
       });
 
       scenarios
@@ -25,7 +25,7 @@ test.describe("config endpoint", () => {
               page
             }) => {
               await page.getByRole("button", { name: otherSize }).click();
-              await expect(page.getByText(`I'm ${otherSize}`)).toBeInViewport();
+              await expect(page.getByText(`I am ${otherSize}`)).toBeVisible();
             });
           });
         });

examples/express/src/routes/config/router.js

@@ -13,7 +13,7 @@ router.get("/*", (req, res) => {
         <link
           rel="preconnect"
           href="https://fonts.gstatic.com"
-          crossOrigin={"true"}
+          crossOrigin="anonymous"
         />
         <link
           href="https://fonts.googleapis.com/css2?family=Didact+Gothic&display=swap"

examples/express/src/routes/parallel-folder-convention/App.tsx

@@ -0,0 +1,25 @@
+import TopBox from "./components/TopBox";
+import BottomBox from "./components/BottomBox";
+import StateProvider from "./StateProvider";
+import { getFeatures, setValue } from "./toggle-plumbing/featuresStore";
+import "./styles.css";
+
+export default function App() {
+  return (
+    <StateProvider>
+      <select
+        onChange={({ target: { value: selection } }) => setValue({ selection })}
+        defaultValue={getFeatures().selection}
+      >
+        <option>baseline 🐶</option>
+        <option value="feature1">feature 1 🐱</option>
+        <option value="feature2">feature 2 🐹</option>
+        <option value="feature3">feature 3 🐰</option>
+        <option value="feature4">feature 4 🦀</option>
+        <option value="feature5">feature 5 🪐</option>
+      </select>
+      <TopBox />
+      <BottomBox />
+    </StateProvider>
+  );
+}

examples/express/src/routes/parallel-folder-convention/README.md

@@ -0,0 +1,143 @@
+# Express "parallel folder convention" example
+
+This example shows the use of the [`react-pointcuts`](../../../../../packages/react-pointcuts/docs/README.md), [`features`](../../../../../packages/features/docs/README.md), [`ssr`](../../../../../packages/ssr/docs/README.md) and [`webpack`](../../../../../packages/webpack/docs/README.md) packages, as part of an [express](https://expressjs.com/) application.
+
+An inbound header named "feature" can take the following values:
+
+- baseline (or omitted)
+- feature1
+- feature2
+- feature3
+- feature4
+- feature5
+
+...which is used server side (via a ["node request scoped features store"](../../../../../packages/features/docs/README.md#noderequestscopedfeaturesstorefactory)) to generate appropriate server-rendered content.
+
+The chosen feature state is serialized to the browser using the `ssr` package, and loaded into a ["global features store"](../../../../../packages/features/docs/README.md#globalfeaturesstorefactory), using [`valtio`](https://github.com/pmndrs/valtio) browser-side, for reactivity.
+
+To demonstrate the reactivity, a drop-down allows changing of the selected feature state.
+
+## Filesystem structure
+
+The base / control folder structure is thus:
+
+```bash
+├── components
+│   ├── Animal
+│   │   └── index.tsx
+│   ├── BottomBox
+│   │   ├── index.tsx
+│   │   └── useAnimals.ts
+│   └── TopBox
+│       ├── TopBoxChild
+│       │   ├── TopBoxButton
+│       │   │   ├── index.module.css
+│       │   │   ├── index.tsx
+│       │   │   └── useAddAnimal.ts
+│       │   └── index.tsx
+│       └── index.tsx
+├── constants
+│   └── index.ts
+└── state
+    ├── modules
+    │   ├── animals
+    │   │   └── slice.ts
+    │   └── index.ts
+    └── store.ts
+```
+
+## Variations
+
+The features comprise the following:
+
+### _baseline_
+
+The base experience. Clicking the dog dispatches a redux action adding a dog to the bottom box.
+
+### _feature1_
+
+Varied react components (`TopBox` & `BottomBox`), at various depths in the folder structure. A varied constant for the animal emoji (`constants/index.ts`) and varied css (background colour of the button) (`TopBoxButton/index.module.css`).
+
+```bash
+├── components
+│   ├── BottomBox
+│   │   └── index.tsx
+│   └── TopBox
+│       ├── TopBoxChild
+│       │   └── TopBoxButton
+│       │       └── index.module.css
+│       └── index.tsx
+└── constants
+    └── index.ts
+```
+
+### _feature2_
+
+Varied constant (`constants/index.ts`), react component (`TopBoxChild`) and redux slice (`slice.ts`) connecting an additional  action creator (`useFreeAnimal.ts`) to "free" added animals (clears the state collection).  Has an alternate "initial state" containing two hamsters, activated during server rendering by a `feature` header containing `feature2`.
+
+```bash
+├── components
+│   └── TopBox
+│       └── TopBoxChild
+│           ├── index.tsx
+│           └── useFreeAnimals.ts
+└── constants
+    └── index.ts
+```
+
+### _feature3_
+
+Varied constant (`constants/index.ts`) & redux slice (`slice.ts`) with modified reducer action that multiplies rabbits, when added.
+
+```bash
+├── constants
+│   └── index.ts
+└── state
+    └── modules
+        └── animals
+            └── slice.ts
+```
+
+### _feature4_
+
+Varied constant (`constants/index.ts`) & redux slice (`slice.ts`) with replaced redux selector that carcinises previously added animals.
+
+```bash
+├── constants
+│   └── index.ts
+└── state
+    └── modules
+        └── animals
+            └── slice.ts
+```
+
+### _feature5_
+
+Varied component (`TopBox`) & redux store (`modules/index.ts`) that introduces a new "space" slice, with it's own state containing spacey stuff.
+
+```bash
+├── components
+│   └── TopBox
+│       ├── index.tsx
+│       ├── styles.module.css
+│       └── useSpaceStuff.ts
+└── state
+    └── modules
+        ├── space
+        │   └── slice.ts
+        └── index.ts
+```
+
+## Explanation
+
+The webpack plugin is configured with a toggle handler that maps variants to controls based on a parallel root folder.  This allows for any file to be replaced at any depth.  The example shows both complete replacements, and augmentations (importing of the base, then modifying).
+
+To vary react components, the toggle point from the `react-pointcuts` package is used.
+
+To vary CSS files, constants, and [`redux` "slices"](https://redux.js.org/tutorials/essentials/part-2-app-structure#redux-slices), a toggle point is used that utilises an [object proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy), to intercept property access.  Despite objects not being innately reactive, as long as they are accessed from something that does update with change of state (i.e. react components), their properties will also update based on the new feature.
+
+To vary `redux` reducer map, a toggle point that wraps the factory method (`getReducerMap`) is used.
+
+To ensure that the redux store is reactive to feature state, a `StateProvider` react component is used to host the [react-redux provider](https://react-redux.js.org/api/provider), that subscribes to the valtio state, and calls [replaceReducer](https://redux.js.org/usage/code-splitting#using-replacereducer) from the [`@reduxjs/toolkit`](https://github.com/reduxjs/redux-toolkit) whenever the feature state changes.  This ensures a new redux store (but retaining current state) is made available to the react components.  Care should be taken to ensure the existing state is compatible with any updated selectors etc.
+
+N.B. It is assumed that feature state will not change during a request cycle on the server, so `valtio` is only plumbed in to the client-side feature store, via conditional compilation using [Webpack's `DefinePlugin`](https://webpack.js.org/plugins/define-plugin/).