Merge branch 'main' into fixversionpolicydocs

docs/source/upgrade-guide/index.md

@@ -16,18 +16,41 @@ Volto uses Semantic Versioning.
 For more information see {doc}`../contributing/version-policy`.
 
 ```{note}
-There are times when updating the Volto boilerplate (the one generated by `@plone/generator-volto`) is enough to fulfill all the changes.
-If you have not heavily modified it, moving things around and copying over your dependencies might do when dealing with upgrades.
-We keep the generator up to date and in sync with the current Volto release.
-When it runs, the generator will tell you whether it is outdated.
-The generator will also "update" your project with the latest changes, and propose to merge the changes.
-Thus it is safe to run it on top of your project and answer the prompts.
+[Cookieplone](https://github.com/plone/cookieplone) is the official project generator for Plone.
+We keep Cookieplone up to date and in sync with the current Volto release.
+
+To make it easier for you to maintain your projects, you should keep all your code inside your project add-ons.
+If you do so, when you want to upgrade your project, you can generate a new project using Cookieplone with the same name as your old one, and copy over your add-ons to the new project.
+It is usually better and quicker to move your items into new locations and copy your dependencies than dealing with following the upgrade steps, regardless of whether you have modified the boilerplate.
 ```
 
 (volto-upgrade-guide-18.x.x)=
 
 ## Upgrading to Volto 18.x.x
 
+(upgrade-18-cookieplone-label)=
+
+### Cookieplone is now the recommended project and add-on generator for Volto 18
+
+```{versionadded} Volto 18.0.0-alpha.43
+```
+
+[Cookieplone](https://github.com/plone/cookieplone) is now the recommended way to develop Volto projects, using it as a boilerplate project generator.
+Cookieplone uses the frontend code installed using `pnpm` instead of `yarn`.
+This affects the way that the Plone Release Team generates the Sponsored OSS Docker images, since they must be compatible with the `pnpm` setup.
+
+Since Volto `18.0.0-alpha.43`, the Docker image [`plone-frontend`](https://hub.docker.com/r/plone/plone-frontend) uses `pnpm`.
+
+For developers that won't migrate their projects to the new setup with `pnpm` instead of `yarn`, the Release Team will generate a new Docker image named `plone-frontend:18-yarn` for the Volto 18 series of alpha releases.
+
+Support for `yarn` will be dropped in Volto 19.
+
+```{deprecated} Volto 18.0.0-alpha.43
+The `yarn`-based generator [`@plone/generator-volto`](https://www.npmjs.com/package/@plone/generator-volto) package and project boilerplates generated from it are deprecated and will not receive any further updates.
+The recommended way of generating a boilerplate project is [Cookieplone](https://github.com/plone/cookieplone).
+Please update your code to use the `pnpm`-based setup.
+```
+
 ### Node.js version support: adding 22, dropping 18
 
 Added support for Node.js 22.
@@ -43,6 +66,11 @@ Version 22 is recommended, as the latest LTS version of Node.js.
 
 ### Volto's internal `dependencies` and `devDependencies` are now properly sorted out
 
+```{deprecated} Volto 18.0.0-alpha.43
+This step is only valid for projects that continue to use the `yarn`-based generator and haven't updated to Cookieplone `pnpm`-based setups.
+See {ref}`upgrade-18-cookieplone-label` for details.
+```
+
 Volto internal `dependencies` and `devDependencies` have been correctly sorted out.
 This means that Volto no longer will force `devDependencies` as `dependencies` just to make sure that they get installed in Volto projects.
 This provoked undesired hoisting problems, and forced the build to not behave correctly in some situations.
@@ -65,6 +93,11 @@ This setting is no longer necessary.
 
 ### New dependencies synchronizer
 
+```{deprecated} Volto 18.0.0-alpha.43
+This step is only valid for projects that continue to use the `yarn`-based generator and haven't updated to Cookieplone `pnpm`-based setups.
+See {ref}`upgrade-18-cookieplone-label` for details.
+```
+
 ```{versionadded} Volto 18.0.0-alpha.21
 ```
 
@@ -147,23 +180,49 @@ As a last resort, you can install `react-portal` as a dependency of your project
 However, this is discouraged, because the React 18 rendering could have unexpected side effects.
 It is recommended that you use the React API instead.
 
-### ESlint project configuration update
+### `@plone/registry` moved to ESM
 
 `@plone/registry` and [other packages on which Volto depends](https://github.com/plone/volto/tree/main/packages) are now stand-alone releases in the monorepo structure released in 18.0.0-alpha.4.
 
-You must update the configuration file {file}`.eslintrc.js` in your projects, according to the following `git diff` patch.
+Also, the `@plone/registry` package has been moved to ESM.
+The add-on registry scripts have also been refactored to TypeScript.
+For maximum compatibility with CommonJS builds, the default exports have been moved to named exports.
+The modules affected are now built, and the import paths have changed, too.
+These changes force some import path changes that you should patch in your Plone project or add-on boilerplates.
+
+```{note}
+As always, when something changes in the boilerplate project generator, you may generate a new project with Cookieplone and move your code into it, instead of manually editing multiple files.
+See {ref}`upgrade-18-cookieplone-label` for details.
+```
+
+For example, in your project's {file}`.eslintrc.js`:
 
 ```diff
-@@ -18,9 +19,6 @@ if (configFile) {
+ const fs = require('fs');
+ const projectRootPath = __dirname;
+-const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
++const { AddonRegistry } = require('@plone/registry/addon-registry');
+
+ let voltoPath = './node_modules/@plone/volto';
+
+@@ -17,15 +17,15 @@ if (configFile) {
      voltoPath = `./${jsConfig.baseUrl}/${pathsConfig['@plone/volto'][0]}`;
  }
 
--const AddonConfigurationRegistry = require(
--  `${voltoPath}/packages/registry/addon-registry.js`,
--);
-const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
+-const reg = new AddonConfigurationRegistry(__dirname);
++const { registry } = AddonRegistry.init(__dirname);
+
+ // Extends ESlint configuration for adding the aliases to `src` directories in Volto addons
+-const addonAliases = Object.keys(reg.packages).map((o) => [
++const addonAliases = Object.keys(registry.packages).map((o) => [
+   o,
+-  reg.packages[o].modulePath,
++  registry.packages[o].modulePath,
+ ]);
+
+-const addonExtenders = reg.getEslintExtenders().map((m) => require(m));
++const addonExtenders = registry.getEslintExtenders().map((m) => require(m));
 
-@@ -38,9 +36,7 @@ const defaultConfig = {
        alias: {
          map: [
            ['@plone/volto', '@plone/volto/src'],
@@ -175,6 +234,22 @@ const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry')
            ['@package', `${__dirname}/src`],
 ```
 
+Also in the Storybook configuration {file}`.storybook/main.js`.
+
+```diff
+-    const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
++    const { AddonRegistry } = require('@plone/registry/addon-registry');
+
+-    const registry = new AddonConfigurationRegistry(projectRootPath);
++    const { registry } = AddonRegistry.init(projectRootPath);
+```
+
+```{versionadded} Volto 18.0.0-alpha.47
+```
+
+```{versionadded} @plone/registry 3.0.0-alpha.0
+```
+
 ### Upgraded Slate libraries
 
 The support libraries for Slate integration have been upgraded, mainly for bug fixes.
@@ -463,30 +538,6 @@ schema: {
 The `Tags` component has been moved to the `belowContent` slot.
 It now receives the `content` property instead of the `tags` property.
 
-
-(upgrade-18-cookieplone-label)=
-
-### Cookieplone is now the recommended project and add-on generator for Volto 18
-
-```{versionadded} Volto 18.0.0-alpha.43
-```
-
-[Cookieplone](https://github.com/plone/cookieplone) is now the recommended way to develop Volto projects, using it as a boilerplate generator.
-Cookieplone uses the frontend code installed using `pnpm` instead of `yarn`.
-This affects the way that the Plone Release Team generates the Sponsored OSS Docker images, since they must be compatible with the `pnpm` setup.
-
-Since Volto `18.0.0-alpha.43`, the Docker image [`plone-frontend`](https://hub.docker.com/r/plone/plone-frontend) uses `pnpm`.
-
-For developers that won't migrate their boilerplate and code to the new setup with `pnpm` instead of `yarn`, the Release Team will generate a new Docker image named `plone-frontend:18-yarn` for the Volto 18 series of alpha releases.
-
-Support for `yarn` will be dropped in Volto 19.
-
-```{deprecated} Volto 18.0.0-alpha.43
-The `yarn`-based generator [`@plone/generator-volto`](https://www.npmjs.com/package/@plone/generator-volto) package and project boilerplates generated from it are deprecated and will not receive any further updates.
-The recommended way of generating a project boilerplate is [Cookieplone](https://github.com/plone/cookieplone).
-Please update your code to use the `pnpm` based setup.
-```
-
 ### Table of Contents block markup change
 
 The `View` component for the Table of Contents block was updated to use a `nav` element instead of a `div`.
@@ -527,63 +578,6 @@ The `react/jsx-key` rule has been enabled in ESlint for catching missing `key` i
 You might catch some violations in your project or add-on code after running ESlint.
 Adding the missing `key` property whenever the violation is reported will fix it.
 
-### `@plone/registry` moved to ESM
-
-The `@plone/registry` package has been moved to ESM.
-The add-on registry scripts have also been refactored to TypeScript.
-For maximum compatibility with CommonJS builds, the default exports have been moved to named exports.
-The modules affected are now built, and the import paths have changed, too.
-These changes force some import path changes that you should patch in your Plone project or add-on boilerplates.
-
-```{note}
-As always, when something changes in the boilerplate, you may regenerate one from Cookieplone and move your code into it, instead of fiddling with it.
-```
-
-For example, in your project's {file}`.eslintrc.js`:
-
-```diff
- const fs = require('fs');
- const projectRootPath = __dirname;
--const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
-+const { AddonRegistry } = require('@plone/registry/addon-registry');
-
- let voltoPath = './node_modules/@plone/volto';
-
-@@ -17,15 +17,15 @@ if (configFile) {
-     voltoPath = `./${jsConfig.baseUrl}/${pathsConfig['@plone/volto'][0]}`;
- }
-
--const reg = new AddonConfigurationRegistry(__dirname);
-+const { registry } = AddonRegistry.init(__dirname);
-
- // Extends ESlint configuration for adding the aliases to `src` directories in Volto addons
--const addonAliases = Object.keys(reg.packages).map((o) => [
-+const addonAliases = Object.keys(registry.packages).map((o) => [
-   o,
--  reg.packages[o].modulePath,
-+  registry.packages[o].modulePath,
- ]);
-
--const addonExtenders = reg.getEslintExtenders().map((m) => require(m));
-+const addonExtenders = registry.getEslintExtenders().map((m) => require(m));
-```
-
-Also in the Storybook configuration {file}`.storybook/main.js`.
-
-```diff
--    const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
-+    const { AddonRegistry } = require('@plone/registry/addon-registry');
-
--    const registry = new AddonConfigurationRegistry(projectRootPath);
-+    const { registry } = AddonRegistry.init(projectRootPath);
-```
-
-```{versionadded} Volto 18.0.0-alpha.47
-```
-
-```{versionadded} @plone/registry 3.0.0-alpha.0
-```
-
 ### Add missing overrides to projects in `package.json`
 
 This will fix some issues with Hot Module Reload in projects.

packages/coresandbox/src/index.ts

@@ -235,6 +235,16 @@ const applyConfig = (config: ConfigType) => {
     predicates: [ContentTypeCondition(['Document']), RouteCondition('/hello')],
   });
 
+  config.registerRoute({
+    type: 'route',
+    path: '/hello',
+    file: 'src/components/Views/NewsAndEvents/asd.tsx',
+    options: {
+      id: 'hello',
+      index: true,
+    },
+  });
+
   return config;
 };
 

packages/registry/docs/how-to-guides/instantiate-registry.md

@@ -46,6 +46,7 @@ export type ConfigData = {
   widgets: WidgetsConfig | Record<string, never>;
   addonReducers?: AddonReducersConfig;
   addonRoutes?: AddonRoutesConfig;
+  routes?: Array<ReactRouterRouteEntry>;
   slots: SlotsConfig | Record<string, never>;
   components: ComponentsConfig | Record<string, never>;
   utilities: UtilitiesConfig | Record<string, never>;

packages/registry/docs/how-to-guides/register-routes.md

@@ -0,0 +1,55 @@
+---
+myst:
+  html_meta:
+    "description": "How to register new routes in @plone/registry"
+    "property=og:description": "How to register new routes in @plone/registry"
+    "property=og:title": "How to register new routes in @plone/registry"
+    "keywords": "Volto, Plone, frontend, React, configuration, routes, React Router"
+---
+
+# Register new routes
+
+The `config.registerRoute` method adds a route to the configuration registry.
+It saves the routes in the `config.routes` key in the configuration object.
+You should provide one route at a time.
+Each route must have the following data shape.
+
+```ts
+type ReactRouterRouteEntry = {
+  type: 'route' | 'index' | 'layout' | 'prefix';
+  path: string;
+  file: string;
+  options?: {
+    id?: string;
+    index?: boolean;
+    caseSensitive?: boolean;
+  };
+  children?: ReactRouterRouteEntry[];
+};
+```
+
+The `type`, `path`, and `file` are mandatory.
+The `type` key specifies the route type to create, specifically one of `route`, `index`, `layout`, or `prefix`.
+The type `route` can contain nested routes.
+
+```{note}
+The routes registered with this method must be compliant with React Router 7 routes.
+They are loaded by a helper provided by `@plone/react-router` in an existing React Router 7 app.
+Check the official [React Router 7 documentation](https://reactrouter.com/start/framework/routing) for more information on how to define React Router 7 routes.
+```
+
+Register a route as shown in the following example.
+
+```ts
+config.registerRoute({
+  type: 'route',
+  path: '/login',
+  file: '@plone/cmsui/components/login.tsx',
+  options: {
+    id: 'login',
+    index: true,
+  },
+});
+```
+
+You must set the module's full path name of the registered route component to make `@plone/registry` correctly address it.

packages/registry/docs/index.md

@@ -4,7 +4,7 @@ myst:
     "description": "@plone/registry provides support for building an add-on and configuration registry with infrastructure for JavaScript and TypeScript-based apps."
     "property=og:description": "@plone/registry provides support for building an add-on and configuration registry with infrastructure for JavaScript and TypeScript-based apps."
     "property=og:title": "@plone/registry"
-    "keywords": "@plone/registry, registry, add-on, configuration, component, utility, JavaScript, TypeScript, app"
+    "keywords": "@plone/registry, registry, add-on, configuration, component, routes, React Router, utility, JavaScript, TypeScript, app"
 ---
 
 # `@plone/registry`
@@ -29,6 +29,7 @@ how-to-guides/access-registry
 how-to-guides/register-and-retrieve-components
 how-to-guides/register-and-retrieve-utilities
 how-to-guides/shadow-a-component
+how-to-guides/register-routes
 ```
 
 

packages/registry/news/6600.feature

@@ -0,0 +1 @@
+Added route registry. @sneridagh

packages/registry/news/6604.documentation

@@ -0,0 +1 @@
+Document the route API. @sneridagh

packages/registry/src/index.ts

@@ -13,6 +13,7 @@ import type {
   UtilitiesConfig,
   ViewsConfig,
   WidgetsConfig,
+  ReactRouterRouteEntry,
 } from '@plone/types';
 
 export type ConfigData = {
@@ -22,6 +23,7 @@ export type ConfigData = {
   widgets: WidgetsConfig | Record<string, never>;
   addonReducers?: AddonReducersConfig;
   addonRoutes?: AddonRoutesConfig;
+  routes?: Array<ReactRouterRouteEntry>;
   slots: SlotsConfig | Record<string, never>;
   components: ComponentsConfig | Record<string, never>;
   utilities: UtilitiesConfig | Record<string, never>;
@@ -126,6 +128,14 @@ class Config {
     this._data.addonRoutes = addonRoutes;
   }
 
+  get routes() {
+    return this._data.routes;
+  }
+
+  set routes(routes) {
+    this._data.routes = routes;
+  }
+
   get slots() {
     return this._data.slots;
   }
@@ -494,6 +504,12 @@ class Config {
 
     return utilities;
   }
+
+  registerRoute(options: ReactRouterRouteEntry) {
+    const route = this._data.routes || [];
+    route.push(options);
+    this._data.routes = route;
+  }
 }
 
 const instance = new Config();