From 4a14f615d93c39246f9b339982a3af0293788882 Mon Sep 17 00:00:00 2001 From: Victor Fernandez de Alba Date: Sat, 14 Dec 2024 12:40:18 +0100 Subject: [PATCH] Add docs and move to use an array --- .../source/configuration/settings-reference.md | 7 +++++++ packages/components/README.md | 12 ++++++++++-- .../components/src/stories/Introduction.mdx | 18 +++++++++++++----- packages/types/src/config/Settings.d.ts | 2 +- packages/volto/src/helpers/Html/Html.jsx | 2 +- 5 files changed, 32 insertions(+), 9 deletions(-) diff --git a/docs/source/configuration/settings-reference.md b/docs/source/configuration/settings-reference.md index 54eaebef20..ae5e32cc76 100644 --- a/docs/source/configuration/settings-reference.md +++ b/docs/source/configuration/settings-reference.md @@ -463,6 +463,13 @@ querystringSearchGet [See an explanation of character limits in URLs](https://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers/417184#417184). Please test this setting properly before enabling in a production site. +cssLayers + If you want to use CSS layers in Volto styling, it's possible to define them making sure that they are defined and applied at the very top level of the page (head tag). + By using this configuration, you can pass the layer list definition as an array: + + ```js + config.settings.cssLayers = ['reset', 'plone-components', 'layout', 'addons', 'theme']; + ``` ``` ## Views settings diff --git a/packages/components/README.md b/packages/components/README.md index af2f8c0589..ba7a55d313 100644 --- a/packages/components/README.md +++ b/packages/components/README.md @@ -62,11 +62,19 @@ Using them as a baseline will allow you to quickly build your theme around them. `@plone/components` basic styles provide a simple, yet powerful, set of tokenized custom CSS properties that will help you customize your own styles on the top of the basic styling. You can override them in your classes while maintaining them for others. +### CSS layers + +This package use CSS layers to provide a way to style the components in a more flexible way. +It uses the `plone-components` layer name to scope all the CSS declarations in the package. +The basic styling uses the nested `plone-components.base` named layer. +You can use the `plone-components` layer to override the basic styling, or use the `plone-components.base` layer to override the basic styling in a more specific way. + ### Quanta This package also features the Quanta components. -The Quanta theme is an example of it. -These components use the basic styling as a baseline, not only in styling, but also in the component side, reusing the CSS and custom CSS properties in it. +These components use the basic styling as a baseline, extending them to achieve Quanta look and feel. +They also extend the basic React components in a composable way. +The Quanta styling is scoped in the `plone-components.quanta` named layer. Quanta is built upon the basic styles in an additive way. The use of the Quanta CSS implies using it upon basic styling. diff --git a/packages/components/src/stories/Introduction.mdx b/packages/components/src/stories/Introduction.mdx index 41ecc9f5d6..8ddefc56b6 100644 --- a/packages/components/src/stories/Introduction.mdx +++ b/packages/components/src/stories/Introduction.mdx @@ -5,16 +5,17 @@ import { Meta } from '@storybook/blocks'; # `@plone/components` -This package contains ReactJS components for using Plone as a headless CMS. +This package contains ReactJS components for Plone 7 and Plone's API-first CMS story. The purpose of this package is to provide an agnostic set of baseline components to build Plone sites upon. ## Usage -Using the package manager of your choice (npm, yarn, pnpm) install the package: +Using the package manager of your choice (npm, yarn, pnpm) to install the package in your app. +Use pnpm in case you are adding them a Volto add-on/workspace: ```shell -yarn add @plone/components +pnpm add @plone/components ``` Whenever you want to use the components, all are exported as named exports: @@ -53,12 +54,19 @@ or selectively: import '@plone/components/src/styles/basic/TextField.css'; ``` +### CSS layers + +This package use CSS layers to provide a way to style the components in a more flexible way. +It uses the `plone-components` layer name to scope all the CSS declarations in the package. +The basic styling uses the nested `plone-components.base` named layer. +You can use the `plone-components` layer to override the basic styling, or use the `plone-components.base` layer to override the basic styling in a more specific way. ## Quanta This package also features the Quanta components. -The Quanta theme is an example of it. -These components use the basic styling as a baseline, not only in styling, but also in the component side, reusing the CSS and custom CSS properties in it. +These components use the basic styling as a baseline, extending them to achieve Quanta look and feel. +They also extend the basic React components in a composable way. +The Quanta styling is scoped in the `plone-components.quanta` named layer. Quanta is built upon the basic styles in an additive way. The use of the Quanta CSS implies using it upon basic styling. diff --git a/packages/types/src/config/Settings.d.ts b/packages/types/src/config/Settings.d.ts index 4c94813e66..61e87a8955 100644 --- a/packages/types/src/config/Settings.d.ts +++ b/packages/types/src/config/Settings.d.ts @@ -101,5 +101,5 @@ export interface SettingsConfig { includeSiteTitle: boolean; titleAndSiteTitleSeparator: string; }; - cssLayers: string; + cssLayers: string[]; } diff --git a/packages/volto/src/helpers/Html/Html.jsx b/packages/volto/src/helpers/Html/Html.jsx index cafcba6d2a..096f485388 100644 --- a/packages/volto/src/helpers/Html/Html.jsx +++ b/packages/volto/src/helpers/Html/Html.jsx @@ -105,7 +105,7 @@ class Html extends Component { {config.settings.cssLayers && ( // Load the CSS layers from config, if any - + )} {head.style.toComponent()}