@maestro-js/react-router-file-routes 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,332 @@
+# Route File Naming (Polaris Adventures)
+
+Adapted from https://remix.run/docs/en/main/file-conventions/route-files-v2
+
+## Basic Routes
+
+Any JavaScript or TypeScript files in the `app/routes/` directory will become routes in your application. The filename maps to the route's URL pathname, except for `index.tsx` which is the [index route](https://remix.run/docs/en/main/guides/routing#index-routes) for the [root route](https://remix.run/docs/en/main/file-conventions/route-files-v2#root-route).
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
++ │   ├── index.tsx
++ │   └── about.tsx
+  └── root.tsx
+```
+
+| URL      | Matched Routes |
+| -------- | -------------- |
+| `/`      | `index.tsx`    |
+| `/about` | `about.tsx`    |
+
+Note that these routes will be rendered in the outlet of `app/root.tsx` because of [nested-routing](https://remix.run/docs/en/main/guides/routing#what-is-nested-routing).
+
+### Dot Delimiters
+
+Adding a `.` to a route filename will create a `/` in the URL.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
+  │   ├── index.tsx
+  │   ├── about.tsx
++ │   ├── concerts.trending.tsx
++ │   ├── concerts.salt-lake-city.tsx
++ │   └── concerts.san-diego.tsx
+  └── root.tsx
+```
+
+| URL                        | Matched Route                 |
+| -------------------------- | ----------------------------- |
+| `/concerts/trending`       | `concerts.trending.tsx`       |
+| `/concerts/salt-lake-city` | `concerts.salt-lake-city.tsx` |
+| `/concerts/san-diego`      | `concerts.san-diego.tsx`      |
+
+### Folder Structure
+
+Adding a parent folder to a route file will also create a `/` in the URL.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
+  │   ├── index.tsx
+  │   ├── about.tsx
++ │   └── concerts
++ │       ├── trending.tsx
++ │       ├── salt-lake-city.tsx
++ │       └── san-diego.tsx
+  └── root.tsx
+```
+
+| URL                        | Matched Route                 |
+| -------------------------- | ----------------------------- |
+| `/concerts/trending`       | `concerts/trending.tsx`       |
+| `/concerts/salt-lake-city` | `concerts/salt-lake-city.tsx` |
+| `/concerts/san-diego`      | `concerts/san-diego.tsx`      |
+
+### Dynamic Segments
+
+Usually your URLs aren't static but data-driven. Dynamic segments allow you to match segments of the URL and use that value in your code. You create them with the `$` prefix.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
+  │   ├── index.tsx
+  │   ├── about.tsx
++ │   └── concerts
++ │       ├── trending.tsx
++ │       └── $city.tsx
+  └── root.tsx
+```
+
+| URL                        | Matched Route           |
+| -------------------------- | ----------------------- |
+| `/concerts/trending`       | `concerts/trending.tsx` |
+| `/concerts/salt-lake-city` | `concerts/$city.tsx`    |
+| `/concerts/san-diego`      | `concerts/$city.tsx`    |
+
+### Nested Routes
+
+You can create nested routes with nested folders. By default, a file with the name `_layout` will become the layout for all routes in that folder.
+
+```diff
+  app/
+  ├── routes/
+  │   ├── index.tsx
+  │   ├── about.tsx
++ │   └── concerts
++ │       ├── _layout.tsx
++ │       ├── $city.tsx
++ │       ├── index.tsx
++ │       └── trending.tsx
+  └── root.tsx
+```
+
+All the routes in the `concerts` folder will be child routes of `concerts/_layout.tsx` and render inside the parent route's outlet.
+
+| URL                      | Matched Route         | Layout                              |
+| ------------------------ | --------------------- | ----------------------------------- |
+| /                        | index.tsx             | `root.tsx`                          |
+| /about                   | about.tsx             | `root.tsx`                          |
+| /concerts                | concerts/index.tsx    | `root.tsx` > `concerts/_layout.tsx` |
+| /concerts/trending       | concerts/trending.tsx | `root.tsx` > `concerts/_layout.tsx` |
+| /concerts/salt-lake-city | concerts/$city.tsx    | `root.tsx` > `concerts/_layout.tsx` |
+
+Note you typically want to add an index route when you add nested routes so that something renders inside the parent's outlet when users visit the parent URL directly.
+
+### Nested Layouts without Nested URLs
+
+We call these **Pathless Routes**
+
+Sometimes you want to share a layout with a group of routes without adding any path segments to the URL. A common example is a set of authentication routes that have a different header/footer than the public pages or the logged in app experience. You can do this with a `_leading` underscore in the folder name.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
++ │   ├── _auth
++ │   │   ├── login.tsx
++ │   │   ├── _layout.tsx
++ │   │   └── register.tsx
+  │   ├── index.tsx
+  │   └── concerts
+  │       ├── _layout.tsx
+  │       └── $city.tsx
+  └── root.tsx
+```
+
+| URL                        | Matched Route        | Layout                              |
+| -------------------------- | -------------------- | ----------------------------------- |
+| `/`                        | `index.tsx`          | `root.tsx`                          |
+| `/login`                   | `_auth/login.tsx`    | `root.tsx` > `_auth/_layout.tsx`    |
+| `/register`                | `_auth/register.tsx` | `root.tsx` > `_auth/_layout.tsx`    |
+| `/concerts/salt-lake-city` | `concerts/$city.tsx` | `root.tsx` > `concerts/_layout.tsx` |
+
+Think of the `_leading` underscore as a blanket you're pulling over the filename, hiding the filename from the URL.
+
+Pathless routes can be used at any nesting level to create additional shared layouts. 
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
+  │   ├── _sales/
+  │   │   ├── _invoices/
+  │   │   │   ├── $invoiceId.tsx
+  │   │   │   ├── index.tsx
+  │   │   │   └── _layout.tsx
+  │   │   ├── overview.tsx
+  │   │   └── _layout.tsx
+  │   └── about.tsx
+  └── root.tsx
+```
+
+| URL         | Matched Route                     | Layout                                                      |
+| ----------- | --------------------------------- | ----------------------------------------------------------- |
+| `/`         | `_sales/_invoices/index.tsx`      | `root.tsx` > `_sales/_layout.tsx` > `_invoices/_layout.tsx` |
+| `/about`    | `about.tsx`                       | `root.tsx`                                                  |
+| `/overview` | `_sales/overview.tsx`             | `root.tsx` > `_sales/_layout.tsx`                           |
+| `/102000`   | `_sales/_invoices/$invoiceId.tsx` | `root.tsx` > `_sales/_layout.tsx` > `_invoices/_layout.tsx` |
+
+
+> Note: Additional `_leading` underscores in a folder name have no effect so that `__sales/` is interpreted the same as `_sales/`. Files with a `_leading` underscore in the name are given no special treatment (`_about.tsx` matches the url `/_about`)
+
+### Optional Segments
+
+Wrapping a route segment in parentheses will make the segment optional.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
++ │   ├── ($lang).tsx
++ │   ├── ($lang).$productId.tsx
++ │   └── ($lang).categories.tsx
+  └── root.tsx
+```
+
+| URL                        | Matched Route            |
+| -------------------------- | ------------------------ |
+| `/`                        | `($lang).tsx`            |
+| `/categories`              | `($lang).categories.tsx` |
+| `/en/categories`           | `($lang).categories.tsx` |
+| `/fr/categories`           | `($lang).categories.tsx` |
+| `/american-flag-speedo`    | `($lang).tsx`            |
+| `/en/american-flag-speedo` | `($lang).$productId.tsx` |
+| `/fr/american-flag-speedo` | `($lang).$productId.tsx` |
+
+You may wonder why `/american-flag-speedo` is matching the `($lang).tsx` route instead of `($lang).$productId.tsx`. This is because when you have an optional dynamic param segment followed by another dynamic param, Remix cannot reliably determine if a single-segment URL such as `/american-flag-speedo` should match `/:lang` `/:productId`. Optional segments match eagerly and thus it will match `/:lang`. If you have this type of setup it's recommended to look at `params.lang` in the `($lang).tsx` loader and redirect to `/:lang/american-flag-speedo` for the current/default language if `params.lang` is not a valid language code.
+
+### Splat Routes
+
+While [dynamic segments](#dynamic-segments) match a single path segment (the stuff between two `/` in a URL), a splat route will match the rest of a URL, including the slashes.
+
+<!-- prettier-ignore -->
+```diff
+  app/
+  ├── routes/
+  │   ├── index.tsx
++ │   ├── $.tsx
+  │   ├── about.tsx
++ │   └── files.$.tsx
+  └── root.tsx
+```
+
+| URL                                          | Matched Route |
+| -------------------------------------------- | ------------- |
+| `/`                                          | `index.tsx`   |
+| `/beef/and/cheese`                           | `$.tsx`       |
+| `/files`                                     | `files.$.tsx` |
+| `/files/talks/remix-conf_old.pdf`            | `files.$.tsx` |
+| `/files/talks/remix-conf_final.pdf`          | `files.$.tsx` |
+| `/files/talks/remix-conf-FINAL-MAY_2022.pdf` | `files.$.tsx` |
+
+### Escaping Special Characters
+
+If you want one of the special characters Remix uses for these route conventions to actually be a part of the URL, you can escape the conventions with `[]` characters.
+
+| Filename                       | URL                |
+| ------------------------------ | ------------------ |
+| `routes/sitemap[.]xml.tsx`     | `/sitemap.xml`     |
+| `routes/[sitemap.xml].tsx`     | `/sitemap.xml`     |
+| `routes/weird-url.[index].tsx` | `/weird-url/index` |
+| `routes/dolla-bills-[$].tsx`   | `/dolla-bills-$`   |
+| `routes/[[so-weird]].tsx`      | `/[so-weird]`      |
+
+## Folders for Organization
+
+All files or folders with a `trailing_` underscore will be excluded from the file based routing. This allows you to organize your code closer to the routes that use them instead of repeating the feature names across other folders.
+
+Consider these routes:
+
+```diff
+  app/
+  ├── routes/
+  │   ├── _landing/
+  │   │   ├── _layout.tsx
+  │   │   ├── about.tsx
+  │   │   └── index.tsx
+  │   ├── work/
+  │   │   ├── _layout.tsx
+  │   │   ├── projects.tsx
+  │   │   └── index.tsx
+  │   └── work.projects.$id.roadmap.tsx
+  └── root.tsx
+```
+
+Some, or all of them can be folders holding additional helper files.
+
+```diff
+  app/
+  ├── routes/
+  │   ├── _landing/
+  │   │   ├── _layout.tsx
+  │   │   ├── about/
+  │   │   │   ├── helpers_
+  │   │   │   │   ├── employee-profile-card.tsx
+  │   │   │   │   ├── get-employee-data.server.tsx
+  │   │   │   │   └── team-photo.jpg
+  │   │   │   └── index.tsx
+  │   │   ├── footer_.tsx
+  │   │   ├── header_.tsx
+  │   │   ├── scroll-experience_.tsx
+  │   │   └── index.tsx
+  │   ├── work/
+  │   │   ├── _layout.tsx
+  │   │   ├── projects/
+  │   │   │   ├── get-projects.server_.tsx
+  │   │   │   ├── project-card_.tsx
+  │   │   │   ├── project-buttons_.tsx
+  │   │   │   └── index.tsx
+  │   │   ├── primary-nav_.tsx
+  │   │   ├── footer_.tsx
+  │   │   ├── stats_.tsx
+  │   │   └── index.tsx
+  │   └── work.projects.$id.roadmap/
+  │       ├── chart_.tsx
+  │       ├── update-timeline.server_.tsx
+  │       └── index.tsx
+  └── root.tsx
+```
+
+```
+# these are the same route:
+routes/work.tsx
+routes/work/index.tsx
+```
+
+# Differences with Remix Routing v1, Remix Routing v2, and Remix Flat Routes 
+
+This routing convention aims to be more flexible than Remix Routing v1, more intuitive than Remix Routing v2, and simpler than 
+Remix Flat Routes. Ultimately this is a matter of choosing your trade-offs and matching personal preferences, but this is the 
+convention which makes most sense for us. 
+
+### Which files are treated as route files? 
+
+**Remix Routing v1:** All files in the `routes` directory becomes routes in the application.
+
+**Remix Routing v2:** All *top-level* files in the `routes` directory become routes in the application, but folders with a `route.tsx`
+file inside will also become routes in the application. Any files in a folder not named `route.tsx` will be ignored. 
+
+**Remix Flat Routes:**  By default all files in the `routes` directory becomes routes in the application. If a folder is suffixed with 
+`+`, only the `index.tsx` file in that folder is treated as a route file.
+
+**Pa Routes**: All files in the `routes` directory becomes routes in the application, unless it (or one or its parent folders) is suffixed with `_`.
+
+
+### How do I define the layout for a set of routes?
+
+**Remix Routing v1:** A file who's name matches the name of an adjacent folder serves as the layout for all files in that folder. 
+
+**Remix Routing v2:**  All the routes that start with `app/routes/concerts.` will be child routes of `app/routes/concerts.tsx`. Sometimes you want 
+the URL to be nested, but you don't want the automatic layout nesting. You can opt out of nesting with a trailing underscore on the parent segment.
+
+**Remix Flat Routes:** All the routes that start with `app/routes/concerts.` will be child routes of `app/routes/concerts.tsx`. Sometimes you want 
+the URL to be nested, but you don't want the automatic layout nesting. You can opt out of nesting with a trailing underscore on the parent segment.
+`app/routes/concerts/_layout.tsx` is equivalent to `app/routes/concerts.tsx`.
+
+**Pa Routes**: Files named `_layout` serve as a layout for all other routes in the same folder.

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+interface Route {
+    path: string | undefined;
+    file: string;
+    index: boolean;
+    layout: boolean;
+    children: Route[];
+    id: string | undefined;
+}
+interface Dir {
+    file: string;
+    contents: (string | Dir)[];
+}
+type ListFilesFunction = (dir: string) => Dir;
+interface PaRoutesOptions {
+    listFiles?: ListFilesFunction;
+}
+interface Alias {
+    file: string;
+    alias: string;
+    children: string[];
+}
+declare function getRoutes(routeDir: string, options?: PaRoutesOptions): Route[];
+declare function defaultListFiles(appDir: string, dirFilename: string): Dir;
+declare function aliasing(routes: Route[], aliases: Alias[]): Route[];
+declare const ReactRouterFileRoutes: {
+    getRoutes: typeof getRoutes;
+    defaultListFiles: typeof defaultListFiles;
+    aliasing: typeof aliasing;
+};
+
+export { ReactRouterFileRoutes };

package/dist/index.js

@@ -0,0 +1,195 @@
+// src/index.ts
+import path from "path";
+import fs from "fs";
+function getRoutes(routeDir, options = {}) {
+  const listFiles = options.listFiles ?? ((routeDir2) => defaultListFiles("app", routeDir2));
+  const dirFiles = listFiles(routeDir);
+  const routes = getRoutesForDir(dirFiles, routeDir);
+  return routes;
+}
+function getRoutesForDir(dir, parentPath) {
+  const layout = dir.contents.find((c) => typeof c === "string" && path.parse(c).name === "_layout");
+  const children = dir.contents.filter((c) => c !== layout).filter((c) => {
+    const name = typeof c === "string" ? path.parse(c).name : path.parse(c.file).name;
+    return !name.endsWith("_") && !name.endsWith(".server");
+  }).flatMap((file) => {
+    if (typeof file === "string") {
+      const index = isIndexFile(file, dir.file);
+      return [
+        {
+          path: index ? "" : getRoutePathForFile(path.parse(file).name, dir.file),
+          file,
+          index,
+          children: [],
+          layout: false,
+          id: void 0
+        }
+      ];
+    } else {
+      return getRoutesForDir(file, dir.file);
+    }
+  });
+  if (layout) {
+    const path2 = getRoutePathForFile(dir.file, parentPath);
+    return [{ path: path2 || void 0, file: layout, children, index: false, layout: true, id: void 0 }];
+  } else {
+    const dirPath = getRoutePathForFile(dir.file, parentPath);
+    return children.map((c) => {
+      const joined = joinPaths(dirPath, c.path);
+      const newPath = joined ? removeTrailingSlashes(joined) : joined;
+      return { ...c, path: newPath };
+    });
+  }
+}
+function joinPaths(...paths) {
+  const filtered = paths.filter((p) => p !== void 0);
+  const result = path.join(...filtered);
+  if (result === ".") {
+    return void 0;
+  } else {
+    return result;
+  }
+}
+function getRoutePathForFile(filePath, dirPath) {
+  const filename = normalizeSlashes(path.relative(dirPath, filePath));
+  const segments = getRouteSegments(filename);
+  const mappedSegments = segments.map((segment) => {
+    if (segment.startsWith("_")) {
+      return "";
+    }
+    if (segment === "$") {
+      return "*";
+    }
+    if (segment.startsWith("$")) {
+      return `:${segment.slice(1)}`;
+    }
+    if (segment.startsWith("($")) {
+      return `:${segment.slice(2, segment.length - 1)}?`;
+    }
+    if (segment.startsWith("(")) {
+      return `${segment.slice(1, segment.length - 1)}?`;
+    }
+    return segment;
+  }).filter((s) => s !== null);
+  const routePath = mappedSegments.join("/");
+  return routePath;
+}
+function isIndexFile(filePath, dirPath) {
+  const relative = normalizeSlashes(path.relative(dirPath, filePath));
+  const isIndex = path.parse(relative).name === "index";
+  return isIndex;
+}
+function removeTrailingSlashes(p) {
+  return p === "/" ? p : p.replace(/\/$/, "");
+}
+function isPathSeparator(char) {
+  return /[\/\\.]/.test(char);
+}
+function getRouteSegments(name, paramPrefixChar = "$") {
+  let routeSegments = [];
+  let i = 0;
+  let routeSegment = "";
+  let state = "START";
+  let subState = "NORMAL";
+  let pushRouteSegment = (routeSegment2) => {
+    if (routeSegment2) {
+      routeSegments.push(routeSegment2);
+    }
+  };
+  while (i < name.length) {
+    let char = name[i];
+    switch (state) {
+      case "START":
+        if (routeSegment.includes(paramPrefixChar) && !(routeSegment.startsWith(paramPrefixChar) || routeSegment.startsWith(`(${paramPrefixChar}`))) {
+          throw new Error(`Route params must start with prefix char ${paramPrefixChar}: ${routeSegment}`);
+        }
+        if (routeSegment.includes("(") && !routeSegment.startsWith("(") && !routeSegment.endsWith(")")) {
+          throw new Error(`Optional routes must start and end with parentheses: ${routeSegment}`);
+        }
+        pushRouteSegment(routeSegment);
+        routeSegment = "";
+        state = "PATH";
+        continue;
+      // restart without advancing index
+      case "PATH":
+        if (isPathSeparator(char) && subState === "NORMAL") {
+          state = "START";
+          break;
+        } else if (char === "[" && subState === "NORMAL") {
+          subState = "ESCAPE";
+          break;
+        } else if (char === "]" && subState === "ESCAPE") {
+          subState = "NORMAL";
+          break;
+        }
+        routeSegment += char;
+        break;
+    }
+    i++;
+  }
+  pushRouteSegment(routeSegment);
+  return routeSegments;
+}
+function normalizeSlashes(file) {
+  return file.split(path.win32.sep).join("/");
+}
+function defaultListFiles(appDir, dirFilename) {
+  const contentsRaw = fs.readdirSync(path.join(appDir, dirFilename));
+  const contents = contentsRaw.map((filename) => {
+    const filePath = path.join(dirFilename, filename);
+    const stat = fs.lstatSync(path.join(appDir, dirFilename, filename));
+    if (stat.isDirectory()) {
+      return defaultListFiles(appDir, filePath);
+    } else if (stat.isFile()) {
+      return path.join(dirFilename, filename);
+    } else {
+      return null;
+    }
+  }).filter((f) => f !== null);
+  return { contents, file: dirFilename };
+}
+function aliasing(routes, aliases) {
+  function getAliasParentInstance(routes2, aliasFile, instance) {
+    routes2.forEach((route) => {
+      if (instance.route) return;
+      if (route.file === aliasFile) {
+        instance.route = route;
+        instance.parent = routes2;
+        return;
+      }
+      if (route.children.length > 0) getAliasParentInstance(route.children, aliasFile, instance);
+    });
+  }
+  aliases.forEach((curr) => {
+    const { file, alias, children } = curr;
+    const instance = { route: void 0, parent: void 0 };
+    getAliasParentInstance(routes, file, instance);
+    if (!instance.route || !instance.parent) {
+      throw new Error(`File ${file}  for ${alias} not found in routes`);
+    }
+    const selectedRoute = instance.route;
+    const parent = instance.parent;
+    parent.push({
+      file: selectedRoute.file,
+      index: selectedRoute.index,
+      children: selectedRoute.children.filter((child) => children?.length && child.path ? children.includes(child.path) : true).map((child) => {
+        return {
+          ...child,
+          id: `${alias}/${child.path}`
+        };
+      }),
+      layout: selectedRoute.layout,
+      path: alias,
+      id: alias
+    });
+  });
+  return routes;
+}
+var ReactRouterFileRoutes = {
+  getRoutes,
+  defaultListFiles,
+  aliasing
+};
+export {
+  ReactRouterFileRoutes
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@maestro-js/react-router-file-routes",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}