Packages READMEs and rules (#5826)

Co-authored-by: Steve Piercy <[email protected]>

PACKAGES.md

@@ -0,0 +1,82 @@
+# Plone frontend packages
+
+This document describes the packages that come with Volto, the default frontend for Plone 6.
+
+
+## `@plone/types`
+
+Plone types is a special development package.
+It contains the Plone typings for TypeScript.
+It's considered a core package, and it's the only package that the other core packages can rely on as
+a `devDependency` in your project configuration.
+
+This package contains `.d.ts` typing definitions, curated by hand.
+Due to the nature of this package, it does not need bundling.
+It's published "as is", so you can import the type definitions from anywhere in your code.
+
+
+## Core packages
+
+-   `@plone/registry`
+-   `@plone/client`
+-   `@plone/components`
+
+
+### Rules
+
+Core packages must not depend on any other `@plone/*` package, with only one exception, `@plone/types`.
+They must be published and bundled in a traditional (transpiled) way.
+The bundle of these packages must work on both CommonJS and ECMAScript Module (ESM) environments.
+
+## Feature packages
+
+-   `@plone/contents`
+
+
+## Utility packages
+
+-   `@plone/blocks`
+-   `@plone/helpers`
+-   `@plone/drivers`
+-   `@plone/rsc`
+
+
+### Rules
+
+Utility packages can depend on core packages and other utility packages.
+They must be published in a traditional way, bundled.
+This bundle must work on both CommonJS and ESM environments.
+
+
+## Development utility packages
+
+These are packages that are not bundled, and they are used in conjunction with Volto core or Volto projects.
+They contain utilities that are useful for the development of a Volto project.
+Some of them are released:
+
+- `@plone/scripts`
+- `@plone/generator-volto`
+
+Some of them are used by the build, and separated in packages for convenience.
+
+- `tsconfig`
+- `parcel-optimizer-react-client`
+
+
+## Volto add-ons packages
+
+These Volto add-ons are packages used by Volto core.
+They are always loaded, so they are also called "core packages".
+The Volto add-ons are not transpiled or bundled.
+They are supposed to be used and built along with a Volto project build.
+
+- `@plone/volto-slate`
+
+
+## Volto testing add-on packages
+
+These packages are used when testing Volto core.
+They contain fixtures that configure features or components that the vanilla Volto core does not have by default.
+Once their fixtures are loaded, they can be tested, for example, in acceptance tests.
+
+- `@plone/volto-coresandbox`

apps/remix/README.md

@@ -1,6 +1,8 @@
 # Plone on Remix
 
-This is a proof of concept of a [Remix](https://remix.run) app, using `@plone/client` and `@plone/components` library. This is intended to serve as both a playground for the development of both packages and as demo of Plone using Remix.
+This is a proof of concept of a [Remix](https://remix.run) app, using the `@plone/client` and `@plone/components` libraries.
+This is intended to serve as both a playground for the development of both packages and as a demo of Plone using Remix.
+
 
 ## Development
 
@@ -17,6 +19,7 @@ Then start the Plone backend:
 make start-backend-docker
 ```
 
+
 ## About this app
 
-- [Remix Docs](https://remix.run/docs)
+- [Remix Docs](https://remix.run/docs/en/main)

packages/blocks/README.md

@@ -0,0 +1,3 @@
+# `@plone/blocks`
+
+This package contains the default blocks provided by Plone.

packages/components/README.md

@@ -97,34 +97,52 @@ It's even possible to use TailwindCSS for styling the components in this package
 
 ### Basic
 
+- BlockToolbar
 - Button
 - Checkbox
-- CheckboxField
-- CheckboxGroup
-- Combobox
 - Container
 - Dialog
-- Form
 - GridList
 - Icon
 - Link
-- Listbox
+- ListBox
 - Menu
 - Modal
-- NumberField
 - Popover
-- RadioGroup
-- Select
-- Switch
+- Slider
+- Table
 - Tabs
 - TagGroup
-- TextField
-- TextAreaField
 - ToggleButton
 - Toolbar
-- BlockToolbar
 - Tooltip
 
+### Forms
+
+- CheckboxField
+- Form
+- Meter
+- NumberField
+- SearchField
+- Select
+- TextAreaField
+- TextField
+- TimeField
+
+### Widgets
+
+- Calendar
+- CheckboxField
+- CheckboxGroup
+- ComboBox
+- DateField
+- DatePicker
+- DateRangePicker
+- ProgressBar
+- RadioGroup
+- RangeCalendar
+- Switch
+
 ### Viewlets
 
 - Breadcrumbs
@@ -138,6 +156,7 @@ It's even possible to use TailwindCSS for styling the components in this package
 
 - TextField
 - TextAreaField
+- Select
 
 ## Quanta icons
 

packages/parcel-optimizer-react-client/README.md

@@ -0,0 +1,4 @@
+# `parcel-optimizer-react-client`
+
+This package is a `parcel` plugin that prepends `use client` to any bundled file.
+This is useful to mark a separation of concerns in frameworks that support React Server Components, like Next.js.

packages/tsconfig/README.md

@@ -0,0 +1,29 @@
+# `tsconfig`
+
+Base configurations for TypeScript projects.
+
+## Usage
+
+In `package.json`:
+
+```json
+  "devDependencies": {
+    "tsconfig": "workspace:*",
+  }
+```
+
+```json
+{
+  "extends": "tsconfig/react-library.json",
+  "include": ["src", "src/**/*.js"],
+  "exclude": [
+    "node_modules",
+    "build",
+    "public",
+    "coverage",
+    "src/**/*.test.{js,jsx,ts,tsx}",
+    "src/**/*.spec.{js,jsx,ts,tsx}",
+    "src/**/*.stories.{js,jsx,ts,tsx}"
+  ]
+}
+```

packages/types/README.md

@@ -1,3 +1,40 @@
 # @plone/types
 
 Plone unified TypeScript typings.
+
+
+## Rules while developing this package
+
+This package contains `.d.ts` typing definitions, curated by hand.
+Due to the nature of this package, it does not need bundling.
+It's published "as is", so you can import the type definitions from anywhere in your code.
+
+The files are organized in the following way:
+
+-   blocks (props related to blocks and blocks components)
+-   config (configuration object typings)
+-   content (content releated and serialization of the content objects)
+-   services (typings concerning Plone REST API services)
+
+
+## Extending existing types in this package in your projects
+
+In a project, you often need to extend the default definitions with your own, for example, when dealing with custom content types or creating new blocks.
+
+You can use TypeScript for extending the types like this:
+
+```ts
+// We extend the block types with our custom ones
+declare module '@plone/types' {
+  export interface BlocksConfigData {
+    myCustomBlock: BlockConfigBase;
+  }
+}
+```
+
+
+## Compatibility
+
+You can use this package from Volto 17 onwards.
+In Volto 17, you should declare it as dependency.
+In Volto 18 and later, it is included by default.