Packages READMEs and rules

PACKAGES.md

@@ -0,0 +1,70 @@
+# Plone frontend packages
+
+## `@plone/types`
+
+Plone types is worth to have its own entry, as it's an 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 devDependency).
+
+This package contains `.d.ts` typing definitions, curated by hand.
+Due to the nature of this package, it does not need bundling.
+It's publised "as it is", so you can import the type definitions from anywhere in your code.
+
+## Core packages
+
+- `@plone/registry`
+- `@plone/client`
+- `@plone/components`
+
+### Rules
+
+They can't 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 ESM environments.
+
+## Feature packages
+
+- `@plone/contents`
+
+## Utility packages
+
+- `@plone/blocks`
+- `@plone/helpers`
+- `@plone/drivers`
+- `@plone/rsc`
+
+### Rules
+
+They 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`
+
+and some of them are used by the build, and separated in packages for convenience.
+
+- `tsconfig`
+- `parcel-optimizer-react-client`
+
+## Volto add-ons packages
+
+These are packages used by Volto core.
+They are loaded always, 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 configuring features or components that the vanila Volto core does not have by default.
+Once their fixtures are loaded, they can be tested, for example, in acceptance tests.
+
+- `@plone/volto-coresandbox`

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,37 @@
 # @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 publised "as it is", so you can import the type definitions from anywhere in your code.
+
+This files are organised 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 RESTAPI 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 it is included by default.