From 806291608e491a9b0bfe1456c619a4d7f1a0c726 Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Wed, 28 Feb 2024 08:54:03 +0100 Subject: [PATCH 1/7] WIP --- PACKAGES.md | 34 ++++++++++++++++++++++++++++++++++ packages/types/README.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 PACKAGES.md diff --git a/PACKAGES.md b/PACKAGES.md new file mode 100644 index 0000000000..7f021e761e --- /dev/null +++ b/PACKAGES.md @@ -0,0 +1,34 @@ +# Plone frontend packages + +## 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 in a traditional way, bundled. +This bundle must work on both commonjs and ESM environments. + +## Special development packages + +- `@plone/types` + +### Rules + +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. + +## Utility packages + +- `@plone/blocks` +- `@plone/helpers` +- `@plone/drivers` +- `@plone/rsc` + +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. diff --git a/packages/types/README.md b/packages/types/README.md index fed41bb418..97bad9f583 100644 --- a/packages/types/README.md +++ b/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. From 424381af85edb6792dd5e98a4fd82ed3931c78fe Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Sun, 3 Mar 2024 23:15:56 +0100 Subject: [PATCH 2/7] A bit more --- PACKAGES.md | 56 +++++++++++++++---- packages/blocks/README.md | 3 + packages/components/README.md | 43 ++++++++++---- .../parcel-optimizer-react-client/README.md | 4 ++ packages/tsconfig/README.md | 29 ++++++++++ 5 files changed, 113 insertions(+), 22 deletions(-) create mode 100644 packages/blocks/README.md create mode 100644 packages/parcel-optimizer-react-client/README.md create mode 100644 packages/tsconfig/README.md diff --git a/PACKAGES.md b/PACKAGES.md index 7f021e761e..6857a06d8d 100644 --- a/PACKAGES.md +++ b/PACKAGES.md @@ -1,5 +1,15 @@ # 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` @@ -9,18 +19,12 @@ ### Rules They can't depend on any other `@plone/*` package, with only one exception: `@plone/types`. -They must be published in a traditional way, bundled. -This bundle must work on both commonjs and ESM environments. - -## Special development packages +They must be published and bundled in a traditional (transpiled) way. +The bundle of these packages must work on both commonjs and ESM environments. -- `@plone/types` - -### Rules +## Feature packages -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. +- `@plone/contents` ## Utility packages @@ -29,6 +33,38 @@ It's publised "as it is", so you can import the type definitions from anywhere i - `@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` 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..15c49bf4e2 --- /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}" + ] +} +``` From 0486ba717f1b2921899b81aefcd3a7ec55d5e79d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Mar 2024 20:34:27 -0800 Subject: [PATCH 3/7] Tidy up PACKAGES.md. --- PACKAGES.md | 53 +++++++++++++++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 20 deletions(-) diff --git a/PACKAGES.md b/PACKAGES.md index 6857a06d8d..955bcc76a4 100644 --- a/PACKAGES.md +++ b/PACKAGES.md @@ -1,43 +1,53 @@ # Plone frontend packages +This document describes the packages that come with Volto, the default frontend for Plone 6. + + ## `@plone/types` -Plone types is worth to have its own entry, as it's an special development package. +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 devDependency). +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 publised "as it is", so you can import the type definitions from anywhere in your code. +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` +- `@plone/registry` +- `@plone/client` +- `@plone/components` + ### Rules -They can't depend on any other `@plone/*` package, with only one exception: `@plone/types`. +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 ESM environments. +The bundle of these packages must work on both CommonJS and ESM environments. + ## Feature packages -- `@plone/contents` +- `@plone/contents` + ## Utility packages -- `@plone/blocks` -- `@plone/helpers` -- `@plone/drivers` -- `@plone/rsc` +- `@plone/blocks` +- `@plone/helpers` +- `@plone/drivers` +- `@plone/rsc` + ### Rules -They can depend on core packages and other utility packages. +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. +This bundle must work on both CommonJS and ESM environments. + ## Development utility packages @@ -48,23 +58,26 @@ 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. +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. +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 configuring features or components that the vanila Volto core does not have by default. +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` From 2da86a2074b5c834d5073394d7a265e494c550ed Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Mar 2024 20:37:18 -0800 Subject: [PATCH 4/7] Use proper case of trademarked name --- packages/parcel-optimizer-react-client/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/parcel-optimizer-react-client/README.md b/packages/parcel-optimizer-react-client/README.md index 15c49bf4e2..dd4d504bfb 100644 --- a/packages/parcel-optimizer-react-client/README.md +++ b/packages/parcel-optimizer-react-client/README.md @@ -1,4 +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. +This is useful to mark a separation of concerns in frameworks that support React Server Components, like Next.js. From 931ce66f24b3709d1b76f365b8e5792f2b829924 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Mar 2024 20:39:55 -0800 Subject: [PATCH 5/7] Tidy up `types/README.md` --- packages/types/README.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/packages/types/README.md b/packages/types/README.md index 97bad9f583..20708b8ee4 100644 --- a/packages/types/README.md +++ b/packages/types/README.md @@ -2,18 +2,20 @@ 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. +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: -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 REST API services) -- 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 @@ -30,8 +32,9 @@ declare module '@plone/types' { } ``` + ## 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. +In Volto 18 and later, it is included by default. From 71ccc52de27a4086328b2218426c884e7baca6bc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 3 Mar 2024 20:49:50 -0800 Subject: [PATCH 6/7] Tidy up `apps/remix/README.md` --- apps/remix/README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) 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) From 6282cffb905f1823c2cb5dcde199e3c60abec352 Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Mon, 4 Mar 2024 09:13:40 +0100 Subject: [PATCH 7/7] Add definition of ESM acronym --- PACKAGES.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/PACKAGES.md b/PACKAGES.md index 955bcc76a4..4baa88756f 100644 --- a/PACKAGES.md +++ b/PACKAGES.md @@ -7,7 +7,7 @@ This document describes the packages that come with Volto, the default frontend 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 +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. @@ -26,8 +26,7 @@ It's published "as is", so you can import the type definitions from anywhere in 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 ESM environments. - +The bundle of these packages must work on both CommonJS and ECMAScript Module (ESM) environments. ## Feature packages