diff --git a/PACKAGES.md b/PACKAGES.md new file mode 100644 index 0000000000..4baa88756f --- /dev/null +++ b/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` diff --git a/apps/remix/README.md b/apps/remix/README.md index 3eab86480c..de9880b2f6 100644 --- a/apps/remix/README.md +++ b/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) diff --git a/packages/blocks/README.md b/packages/blocks/README.md new file mode 100644 index 0000000000..c53c030b59 --- /dev/null +++ b/packages/blocks/README.md @@ -0,0 +1,3 @@ +# `@plone/blocks` + +This package contains the default blocks provided by Plone. diff --git a/packages/components/README.md b/packages/components/README.md index 0731a8e49f..af2f8c0589 100644 --- a/packages/components/README.md +++ b/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 diff --git a/packages/parcel-optimizer-react-client/README.md b/packages/parcel-optimizer-react-client/README.md new file mode 100644 index 0000000000..dd4d504bfb --- /dev/null +++ b/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. diff --git a/packages/tsconfig/README.md b/packages/tsconfig/README.md new file mode 100644 index 0000000000..c94118473f --- /dev/null +++ b/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}" + ] +} +``` diff --git a/packages/types/README.md b/packages/types/README.md index fed41bb418..20708b8ee4 100644 --- a/packages/types/README.md +++ b/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.