diff --git a/.github/workflows/docs-rtd-pr-preview.yml b/.github/workflows/docs-rtd-pr-preview.yml new file mode 100644 index 00000000..7ea4a840 --- /dev/null +++ b/.github/workflows/docs-rtd-pr-preview.yml @@ -0,0 +1,24 @@ +# .github/workflows/docs-rtd-pr-preview.yml +name: readthedocs/actions +on: + pull_request_target: + types: + - opened + # Execute this action only on PRs that touch + # documentation files. + paths: + - "docs/**" + - .readthedocs.yaml + - requirements-docs.txt + +permissions: + pull-requests: write + +jobs: + documentation-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "volto-light-theme" + single-version: "true" diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..73b3212d --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,43 @@ +name: Documentation +on: + push: + branches: + - main + paths: + - 'docs/**' + # Build pull requests + pull_request: + paths: + - 'docs/**' + - 'styles/**' + - '.github/workflows/docs.yml' + - 'requirements-docs.txt' + +jobs: + docs: + name: Documentation + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.12'] + steps: + - uses: actions/checkout@v4 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + cache: 'pip' + cache-dependency-path: 'requirements-docs.txt' + + - name: Create Python virtual environment + run: pip install virtualenv + + - name: pip install requirements + run: pip install -r requirements-docs.txt + + - name: Check for broken links + run: make docs-linkcheckbroken + + - name: Build HTML documentation + run: make docs-html diff --git a/.gitignore b/.gitignore index 01fd008a..c923072a 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,8 @@ core build .DS_Store public + +/bin +/lib +pyvenv.cfg +docs/_build diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..823aec29 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,32 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: requirements-docs.txt diff --git a/Makefile b/Makefile index aa7a3cb5..b3ccae05 100644 --- a/Makefile +++ b/Makefile @@ -10,6 +10,18 @@ MAKEFLAGS+=--no-builtin-rules CURRENT_DIR:=$(shell dirname $(realpath $(lastword $(MAKEFILE_LIST)))) +# Sphinx variables +# You can set these variables from the command line. +SPHINXOPTS ?= +VALEOPTS ?= +# Internal variables. +SPHINXBUILD = "$(realpath bin/sphinx-build)" +SPHINXAUTOBUILD = "$(realpath bin/sphinx-autobuild)" +DOCS_DIR = ./docs/ +BUILDDIR = ./_build/ +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) . +VALEFILES := $(shell find $(DOCS_DIR) -type f -name "*.md" -print) + # Recipe snippets for reuse # We like colors @@ -32,6 +44,60 @@ ADDON_NAME='@kitconcept/volto-light-theme' help: ## Show this help @echo -e "$$(grep -hE '^\S+:.*##' $(MAKEFILE_LIST) | sed -e 's/:.*##\s*/:/' -e 's/^\(.\+\):\(.*\)/\\x1b[36m\1\\x1b[m:\2/' | column -c2 -t -s :)" +## Docs + +bin/python: ## Create a Python virtual environment with the latest pip, and install documentation requirements + python3 -m venv . || virtualenv --clear --python=python3 . + bin/python -m pip install --upgrade pip + @echo "Python environment created." + bin/pip install -r requirements-docs.txt + @echo "Requirements installed." + +.PHONY: docs-clean +docs-clean: ## Clean current and legacy docs build directories, and Python virtual environment + rm -rf bin include lib + rm -rf docs/_build + cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/ + +.PHONY: docs-html +docs-html: bin/python ## Build html + cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: docs-livehtml +docs-livehtml: bin/python ## Rebuild Sphinx documentation on changes, with live-reload in the browser + cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \ + --ignore "*.swp" \ + -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) + +.PHONY: docs-linkcheck +docs-linkcheck: bin/python ## Run linkcheck + cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/ ." + +.PHONY: docs-linkcheckbroken +docs-linkcheckbroken: bin/python ## Run linkcheck and show only broken links + cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | GREP_COLORS='0;31' grep -wi "broken\|redirect" --color=always | GREP_COLORS='0;31' grep -vi "https://github.com/plone/volto/issues/" --color=always && if test $$? -eq 0; then exit 1; fi || test $$? -ne 0 + +.PHONY: docs-vale +docs-vale: bin/python ## Install (once) and run Vale style, grammar, and spell checks + bin/vale sync + bin/vale --no-wrap $(VALEOPTS) $(VALEFILES) + @echo + @echo "Vale is finished; look for any errors in the above output." + +.PHONY: docs-rtd-pr-preview +docs-rtd-pr-preview: ## Build previews of pull requests that have documentation changes on Read the Docs via CI + pip install -r requirements-docs.txt + cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ + +.PHONY: docs-rtd-registry +docs-rtd-registry: ## Build Plone Registry docs on RTD + pip install -r ../../requirements-docs.txt && cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ + # Dev Helpers .PHONY: install diff --git a/README.md b/README.md index 37091597..ba4dfc81 100644 --- a/README.md +++ b/README.md @@ -5,380 +5,20 @@ [![Build Status](https://github.com/kitconcept/volto-light-theme/actions/workflows/unit.yml/badge.svg)](https://github.com/kitconcept/volto-light-theme/actions) [![Build Status](https://github.com/kitconcept/volto-light-theme/actions/workflows/acceptance.yml/badge.svg)](https://github.com/kitconcept/volto-light-theme/actions) -![kitconcept GmbH](https://github.com/kitconcept/volto-blocks/raw/master/kitconcept.png) +![kitconcept GmbH](https://raw.githubusercontent.com/kitconcept/volto-blocks/master/kitconcept.png) ## Vision -The main vision of the Volto Light Theme is to serve as a foundation for kitconcept's future projects, following the release of Plone 6. - -It contains the feedback from the company's last years projects and the success stories in the UI/UX side. - -It aims to be future proof, so it has to be aligned with the upcoming Volto vision in terms of theming strategy decided by the Plone community. +The main vision of the Volto Light Theme (VLT) is to serve as a foundation for kitconcept's future projects, following the release of Plone 6. +It incorporates feedback from the company's clients and Plone community from the last few years of projects and the success stories in the UI/UX side. +It aims to be future-proof, keeping it aligned with the upcoming Volto and Plone 7 vision in terms of theming strategy decided by the Plone community. ![Volto-Light-Theme](https://github.com/kitconcept/volto-light-theme/raw/main/volto-light-theme.png) -## Requirements and specs - -### It should not use any SemanticUI component or styling - -Volto will abandon SemanticUI as default design component system in the mid term, and we should be prepared for it. - -We will achieve that by not using any SemanticUI component, nor any related styling (`.ui.XXX`) in our upcoming themes. - -The Volto strategy is: - -- Provide a very basic and structural Vanilla components to build upon theming and CMSUI as well (`@plone/components`) -- These components will be based in a headless component system [React Aria Components](https://react-spectrum.adobe.com/react-aria/components.html) -- Volto projects can be themed using `@plone/components` as baseline or use a complete different design or component system of the developer/integrator choice. The presence of Volto's component registry system could help for adapting, if required. - -#### Volto components `customizations` use case - -If possible, we will switch to SemanticUI-less components when `@plone/components` is ready. -Specially if the elements that we are customizing are clearly "theme" (eg. header/footer, etc). -In the case of other Volto customizations that are not clear part of the theme (eg. Search block), it's fine to stick using what the original is using (SemanticUI). -When Volto will make the switch in the future, we should then adapt all the customizations to match the one in the Volto core. -The approach used is to use a proxy to a component of the `components` folder. This way it's easier to keep track of changes, and another add-on can customize again the light theme component, not the original Volto customization. - -### It should use kitconcept's layout used in FZJ/DLR projects - -Since FZJ/DLR projects we've been trying a new concept in layout for Volto. This new layout uses three widths for the content elements: - -- Narrow (text) -- Default (blocks) -- Layout (main screen elements like Header, Footer) - -The Layout sized elements snap to 1440px. The breakpoints are also different than default Volto. - -This new layout uses mixin's and CSS that can be found in `layout.less` in the theme folder. - -Since the new container queries spec is out, we will be introducing it to the current CSS in order to implement the complexities that the "inner container" (the one between the toolbar and the sidebar) width presents. Until now, we did complex calculations given into account if the size of the inner container depending if the toolbar, the sidebar, or both were presents. With container queries we can do that in a more sensible and easy way. - -### Organization of the files - -We will start organising the files in the root of `theme` folder, to differentiate from a normal "SemanticUI" theme. Take a look at the current state. We will follow this convention: - -- One file per component/block -- Use the Volto theme facility using the SCSS scape hatch provided so other add-ons can hook to it. -- The styling is centralized in `main.scss`, the rest of the files are loaded from there. - -## Why a headless component system? - -https://medium.com/@nirbenyair/headless-components-in-react-and-why-i-stopped-using-ui-libraries-a8208197c268 - -## Vertical spacing block model - -This theme has the concept of block "grouping" given two consecutive blocks with the same styling block wrapper property `backgroundColor`. You have to add this property to your blocks in your blocks code. This add-on customizes `RenderBlocks.jsx` component in order to do so. - -The wrappers have the classnames `blocks-group-wrapper` and the name of the background color, eg. `grey`, defaulting to `transparent` if no `backgroundColor` property is set in the styling block wrapper in the block. - -**Disclaimer**: This might change in the near future, since we are developing a new integral Block Model for VLT and Volto. - -### Vertical spacing rules - -These main rules spec applies to the theme: - -- On each change of color, a vertical padding (both `padding-bottom` and `padding-top`) of `80px` defined with the main variable `$color-block-change-vertical-spacing`. -- The default bottom margin is defined with the main variable `$block-vertical-space` and set by default to `25px`. -- [grid] Vertical spacing for grids should be `80px` for both top and bottom, even if the previous and next blocks are of the same color. -- [grid+grid] When two grids happen side by side and are of the same color. It should be equal to the grid gap, so it's set to `@gutterWidth` and currently `1rem`. It has to be adjusted with a bit of negative margin to cancel the current inner padding in grid cells. -- [grid+grid] Grids columns belonging to the same grid and same color in small mobile viewports. They should be closer to match the other adjacent ones, so they seem to belong to the same grid set. -- [footer] The footer has a top vertical spacing of `80px`. -- [teasers] The last teaser, except if the following is a button, does NOT have a line at the bottom. -- [listing] The last listing, except if the following is a button, does NOT have a line at the bottom. -- [listing] After two consecutive listings, the vertical spacing should be `200px`. -- [text+button] If there's a text and a button, then the vertical spacing betweeen them is `60px`. -- [image+separator-block] If after image comes a separator block, the vertical spacing between them is `40px`. - -### Media queries vs container queries - -We use media queries when the styling it's generic enough to apply only to the View. - -We use container queries when do care explicitly about how the styling is being applied in edit mode as well and we want the content area to behave 1:1 with the view mode. - -Reason: The container queries allow us to abstract the width from the sidebar and toolbar in edit mode, showing the content area as it will be in that size, in view mode. - -**Remember**: The margins in responsive are being taken care with container queries in `layout.scss`. So everything related to that, goes like it works in there, with container queries. See implementations for details in case you need it. - -## Specification - -`@kitconcept/volto-light-theme` works with the following Plone Blocks: - -- Grid-Block (https://www.npmjs.com/package/@kitconcept/volto-blocks-grid) -- Teaser-Block (https://www.npmjs.com/package/@kitconcept/volto-blocks-grid) -- Slider-Block (https://www.npmjs.com/package/@kitconcept/volto-slider-block) -- Button-Block (https://www.npmjs.com/package/@kitconcept/volto-button-block) -- Separator-Block (https://www.npmjs.com/package/@kitconcept/volto-separator-block) -- Heading-Block (https://www.npmjs.com/package/@kitconcept/volto-heading-block) -- Introduction-Block (https://www.npmjs.com/package/@kitconcept/volto-introduction-block) -- Accordion-Block (https://www.npmjs.com/package/@eeacms/volto-accordion-block) - -and the following add-ons: - -- DSGVO-Banner (https://www.npmjs.com/package/@kitconcept/volto-dsgvo-banner) - -## Installation - -It is recommended that your project or policy add-on `package.json` include the aforementioned add-ons. - -```json - "dependencies": { - "@eeacms/volto-accordion-block": "^10.4.0", - "@kitconcept/volto-button-block": "^2.3.1", - "@kitconcept/volto-dsgvo-banner": "^1.3.0", - "@kitconcept/volto-heading-block": "^2.4.0", - "@kitconcept/volto-highlight-block": "^3.0.0", - "@kitconcept/volto-introduction-block": "^1.0.0", - "@kitconcept/volto-separator-block": "^4.0.0", - "@kitconcept/volto-slider-block": "^6.0.0", - "@kitconcept/volto-light-theme": "^2.0.0", - } -``` - -This theme won't install them for you, as they are declared as `peerDependencies`. -This is because the theme won't have to force you to use any specific add-on version, and avoids package hoisting issues. - -In your project or policy add-on `package.json` you should declare all of them as Volto add-ons - -```json - "addons": [ - "@eeacms/volto-accordion-block", - "@kitconcept/volto-button-block", - "@kitconcept/volto-heading-block", - "@kitconcept/volto-introduction-block", - "@kitconcept/volto-highlight-block", - "@kitconcept/volto-separator-block", - "@kitconcept/volto-light-theme", - "your_policy_addon_here" - ], -``` - -Make sure your policy add-on is the last one, as you would want that its configuration has priority over all the others. Make sure also that `@kitconcept/volto-light-theme` is the one before your policy add-on. - -Then, declare the theme in your project `package.json`: - -```json - "theme": "@kitconcept/volto-light-theme", -``` - -Alternatively, you can also declare it in your project's `volto.config.js`: - -```js -const addons = []; -const theme = '@kitconcept/volto-light-theme'; - -module.exports = { - addons, - theme, -}; -``` - -You can specify your project add-ons in `volto.config.js`, but sometimes is better to have them all in one place (in your policy add-on) for portability. - -## Feature Flags - -### Enable Fat Menu - -Since 2.0.0, the light theme has a fat menu (below the main site sections) triggered clickin on one of them. -It's behind a feature flag, as opt-out: - -```js -config.settings.enableFatMenu = true; -``` - -### Show Site Label - -If you want to show a label on top of site you can pass label name to `siteLabel` property. +## Documentation -```js -config.settings.siteLabel = 'Plone Intranet'; -``` - -If you wanted a translated label then you have to define a translation object in `defineMessages` function provided by react-intl. - -Here is the code snippets you have to add in your addon index.js file. -If you don't have addon, you can also add in your config.js file in root of your frontend folder. - -```js -import { defineMessages } from 'react-intl'; - -defineMessages({ - siteLabel: { - id: 'siteLabel', - defaultMessage: ' ', - }, -}); - -``` -Then add the translation you want in your `locale` file. - -### Show intranetHeader - -We have totally different header for intranet sites. If you want that, you can enable it by passing `intranetHeader` property. - -```js -config.settings.intranetHeader = true; -``` -## Releases - -The releases follow a semantic versioning model. - -### Definition of breaking change - -In general, the same rules as Volto releases applies. -However, in VLT we add an extra exception: The vertical spacing is carefully curated and considered an important feature of the theme and because of that, changes and improvements in the vertical spacing are **NOT** considered breaking changes. -They will be noted properly in the changelog. +You can find the documentation of this package at https://volto-light-theme.readthedocs.io. ## Upgrade Guide -See a detailed upgrade guide in: https://github.com/kitconcept/volto-light-theme/blob/main/UPGRADE-GUIDE.md - -## Compatibility - -| VLT version | Volto version | -|-------------|---------------| -| 3.x.x | >= Volto 17.0.0-alpha.16 | -| 4.x.x | < Volto 17.18.0 | -| 5.x.x | >= Volto 17.18.0 or >=Volto 18.0.0-alpha.36 | - -Compatibility with Volto 16 might be achieved, but it has to be at customization level in the specific project add-on. -This is mainly due to the `RenderBlocks` customization that is based in the one in 17 because of the Grid block in core and the autogrouping feature. -See more information about the other dependencies in `peerDependencies` in `package.json`. - -## Development - -The development of this add-on is done in isolation using a new approach using pnpm workspaces and latest `mrs-developer` and other Volto core improvements. -For this reason, it only works with pnpm and Volto 18 (currently in alpha) but it does not mean that the add-on will only work in 18. - -### Development requisites - -- Volto 18 (2024-03-21: currently in alpha) -- pnpm as package manager - -### Make convenience commands - -Run `make help` to list the available commands. - -```text -help Show this help -install Installs the add-on in a development environment -start Starts Volto, allowing reloading of the add-on during development -build Build a production bundle for distribution of the project with the add-on -build-deps Build dependencies -i18n Sync i18n -ci-i18n Check if i18n is not synced -format Format codebase -lint Lint, or catch and remove problems, in code base -release Release the add-on on npmjs.org -release-dry-run Dry-run the release of the add-on on npmjs.org -test Run unit tests -ci-test Run unit tests in CI -backend-docker-start Starts a Docker-based backend for development -storybook-start Start Storybook server on port 6006 -storybook-build Build Storybook -acceptance-frontend-dev-start Start acceptance frontend in development mode -acceptance-frontend-prod-start Start acceptance frontend in production mode -acceptance-backend-start Start backend acceptance server -ci-acceptance-backend-start Start backend acceptance server in headless mode for CI -acceptance-test Start Cypress in interactive mode -ci-acceptance-test Run cypress tests in headless mode for CI -acceptance-a11y-frontend-prod-start Start a11y acceptance frontend in prod mode -ci-acceptance-a11y-backend-start Start acceptance a11y server in CI mode (no terminal attached) -acceptance-a11y-test Start a11y Cypress in interactive mode -ci-acceptance-a11y-test Run a11y cypress tests in headless mode for CI -``` - -### Development Environment Setup - -Install package requirements - -```shell -pnpm i -make install -pnpm i -``` - -### Start developing - -Run (in separate terminal sessions) - -Start backend server - -```shell -make start-backend-docker -``` - -Start frontend - -```shell -pnpm start -``` - -### Linting - -Run ESlint, Prettier and Stylelint - -```shell -make lint -``` - -### Formatting - -Run ESlint, Prettier and Stylelint in fix mode - -```shell -make format -``` - -### i18n - -Extract the i18n messages to locales - -```shell -make i18n -``` - -### Unit tests - -Run unit tests - -```shell -make test -``` - -### Run Cypress tests - -Run (in separate terminal sessions) - -Start the frontend in dev mode - -```shell -make start-test-acceptance-frontend-dev -``` - -Start the backend acceptance server - -```shell -make start-test-acceptance-server -``` - -Start the Cypress interactive test runner - -```shell -make test-acceptance -``` - -### Release - -Run - -```shell -make release -``` - -For releasing a RC version - -Run - -```shell -make release-rc -``` +See a detailed upgrade guide at https://volto-light-theme.readthedocs.io/latest/upgrade-guide.html. diff --git a/UPGRADE-GUIDE.md b/UPGRADE-GUIDE.md deleted file mode 100644 index 88e83943..00000000 --- a/UPGRADE-GUIDE.md +++ /dev/null @@ -1,57 +0,0 @@ -# Upgrade Guide - -## volto-light-theme 5.0.0 - -The requirements for VLT have changed: - -| VLT version | Volto version | -|-------------|---------------| -| 3.x.x | >= Volto 17.0.0-alpha.16 | -| 4.x.x | < Volto 17.18.0 | -| 5.x.x | >= Volto 17.18.0 or >=Volto 18.0.0-alpha.36 | - -## volto-light-theme 4.0.0 - -The tabbing order in the top header was fixed for accessibility concerns. -It modifies the underlying HTML to move the top header to the bottom, and modifies CSS to adjust. - -The MobileNavigation component was updated to be more easily customizable. -The component can now handle infinite navigation depth instead of only three levels, if configured to do so. -The Burger Menu can now be easily customized by overriding the new MobileNavigationToggler.jsx file. - -## volto-light-theme 3.0.0 - -### Blocks background colors go full width - -The background colors previously used to snap to 1440px. -From 3.0.0-alpha.0 this changed to be unconstrained by default, and expand to the end of the horizontal viewport. - -### Upgraded support for volto-slider-block 6.0.0 - -VLT upgraded the dependency on `@kitconcept/volto-slider-block` to use `6.0.0`. - -This is a drop-in replacement, so no action is required for the existing slider blocks you may have already in your sites. -However, the CSS classes of the structural slider block elements changed in this version. -The inner (visible objects) CSS classes remain unchanged. -If you have customized them in your project, you may have to update them, although the structural class names are rarely customized aside from vertical spacing properties. -They are mapped 1:1 with the previous ones, following this table correspondence: - -| Old className | New className | -| --------------- | ---------------- | -| slick-slider | slider-wrapper | -| slick-list | slider-viewport | -| slick-track | slider-container | -| slick-slide | slider-slide | -| slick-arrow | slider-button | -| slick-prev | slider-button-prev | -| slick-next | slider-slide-next | -| slick-next | slider-slide-next | -| slick-dots | slider-dots | -| slick-dot | slider-dot | - -For more information, please check the https://github.com/kitconcept/volto-slider-block/blob/main/README.md [#288](https://github.com/kitconcept/volto-light-theme/pull/288) - -### Language switcher shows the two letters abbreviation of the languages - -Volto default is to show the full name of the language in the language switcher. -VLT now shows only the two letters abbreviation of the language. diff --git a/docs/_static/Plone_logo_square.png b/docs/_static/Plone_logo_square.png new file mode 100644 index 00000000..f42a1220 Binary files /dev/null and b/docs/_static/Plone_logo_square.png differ diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 00000000..ae7bb0cd Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_static/logo.svg b/docs/_static/logo.svg new file mode 100644 index 00000000..6bfdc1ee --- /dev/null +++ b/docs/_static/logo.svg @@ -0,0 +1,48 @@ + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/print.css b/docs/_static/print.css new file mode 100644 index 00000000..8dbc2d57 --- /dev/null +++ b/docs/_static/print.css @@ -0,0 +1,3 @@ +.tooltip { + display: none; +} diff --git a/docs/_static/volto-light-theme.png b/docs/_static/volto-light-theme.png new file mode 100644 index 00000000..aa487310 Binary files /dev/null and b/docs/_static/volto-light-theme.png differ diff --git a/docs/block-model-v3.md b/docs/block-model-v3.md new file mode 100644 index 00000000..09dcabb0 --- /dev/null +++ b/docs/block-model-v3.md @@ -0,0 +1,120 @@ +--- +myst: + html_meta: + "description": "Block model version 3" + "property=og:description": "Block model version 3" + "property=og:title": "Block model version 3" + "keywords": "Volto Light Theme, Block model version 3" +--- + +# Block model version 3 + +## Introduction and history + +### DLR Block model (v1) + +The block has all the information needed for rendering itself, but the rules are exhaustive, cumbersome, and prone to error if they are not exhaustive enough. + + +### VLT Block model (v2) + +After the DLR experience, we tried the approach of using a block wrapper in view mode that would arrange the blocks grouped by a property, background color, and wrapped in a container. +This container is the one with the vertical spacing and the color. +This proved to dramatically simplify the CSS, with the drawback that the wrapper and the arrangement logic should be present in the view mode. +This made it very difficult to do the same in edit mode, because of the existing drag-and-drop wrappers, so the edit mode renders "ugly" without them. + + +## Block Model version 3 + +### View/Edit containers + +The block should have the same containers in both View and Edit components, so we can write CSS once that applies to both. + +These containers will conform the following two-level wrappers definitions. + + +#### Main/Outer container + +This is the container that receives the injected block classNames and styles from the StyleWrapper. +It's the (familiar) `div` that has the `block ${type}` className. +In View mode it should be provided by the block developer. +In Edit mode it's part of the edit wrappers, `block-editor-${type}` wrapper, and automatically receives the StyleWrapper injected properties. + +The principal responsibility of the Main/Outer container, other than giving the block its background color, is to fit the block into the layout of the page by stacking itself above or below its siblings. +It _must_ be full width, and go from the left edge to the right edge of the page. +It _must not_ have any margin or padding. +The only exception to this is the extra padding that is added for visual coherence when the block's background color is different from the previous or next sibling's background color. + + +#### Secondary/Inner container + +The Secondary/Inner container takes care of the horizontal (block's content width) and vertical (vertical spacing between siblings) offsets. +For example, for a block such as the Slider, you might want to have a horizontal offset of zero, and have the content fill the width of the page. +On the other hand, for a Slate with a paragraph of text, you might want space offsetting both sides to facilitate readability and create a cleaner look. + +The vertical spatial relationships between contiguous blocks will be defined by the blocks' categories. +For example, if a Slate (which has category inline) comes after a Slider (which has category full-width), the latter should add an extra bottom padding to improve the readability of the following paragraph. + +To avoid background color inconsistencies, the vertical offset given by the Secondary/Inner container must be implemented using the padding property. +As a general rule—and to establish a convention—the vertical space between two blocks should be provided by the upper block. +This means that, for most cases, the top of the block's content must be flush with the top of the container. + + +### Block category + +A block should be able to be categorized given its nature and visual characteristics. +This nature determines how they relate with the other siblings. + +This category will help to determine the default behavior of the block by injecting it as a className. + + +### Improve the edit mode wrappers + +We can improve the current edit wrappers, but we have to do it in a non-breaking way. + +Current Edit mode wrappers: + +```text +.block-editor-$type $StyleWrapperClassNames $StyleWrapperStyles + div.[style="position: relative"] (the relative container) + div.drag.handle.wrapper (the one of the drag icon) + div.ui.drag.block.inner.$type (this is superfluous, but the block classname can't be removed) + div.[role="presentation"].block.$type.selected (the state-wrapper, controls the blue border) + {Edit component} + button.ui.basic.button.delete-button +``` + +Proposed wrappers: + +Edit + +```text +.block-editor-$type $StyleWrapperClassNames $StyleWrapperStyles + div.[style="position: relative"] (the relative container) + div.drag.handle.wrapper (the one of the drag icon) + div.ui.drag.block.inner.$type (this is superfluous, but the block classname can't be removed) + div.[role="presentation"].block.$type.selected category-action +
+ {Edit component} +
+ button.ui.basic.button.delete-button +``` + +View + +```jsx +
+
+ {View component} +
+
+``` + +CSS + +```css +.block-editor-button, +.button.button { + background: var(--background-color) +} +``` diff --git a/docs/compatibility.md b/docs/compatibility.md new file mode 100644 index 00000000..8564470f --- /dev/null +++ b/docs/compatibility.md @@ -0,0 +1,20 @@ +--- +myst: + html_meta: + "description": "Volto Light Theme compatibility" + "property=og:description": "Volto Light Theme compatibility" + "property=og:title": "Compatibility" + "keywords": "Volto Light Theme, Compatibility" +--- + +# Compatibility + +| VLT version | Volto version | +|-------------|---------------| +| 3.x.x | >= Volto 17.0.0-alpha.16 | +| 4.x.x | < Volto 17.18.0 | +| 5.x.x / 6.x.x | >= Volto 17.18.0 or >=Volto 18.0.0-alpha.36 | + +Compatibility with Volto 16 might be achieved, but it has to be at the customization level in the specific project add-on. +This is mainly due to the `RenderBlocks` customization that is based on the one in Volto 17, because of the Grid block in core and the autogrouping feature. +See more information about the other dependencies in `peerDependencies` in {file}`package.json`. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..a8bc2209 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,239 @@ +# Configuration file for the Sphinx documentation builder. +# Plone Documentation build configuration file + + +# -- Path setup -------------------------------------------------------------- + +from datetime import datetime + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath(".")) + +import os +import json + + +# -- Project information ----------------------------------------------------- + +project = "@kitconcept/volto-light-theme documentation" +copyright = "Plone Foundation" +author = "kitconcept, GmbH" +trademark_name = "Plone" +now = datetime.now() +year = str(now.year) + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +with open(os.path.join(os.path.abspath("."), "../package.json"), "r") as package_json: + data = package_json.read() + +version_from_package_json = json.loads(data)["version"] + +if version_from_package_json: + # The short X.Y version. + version = version_from_package_json + # The full version, including alpha/beta/rc tags. + release = version_from_package_json +else: + version = "6.0.0" + release = "6.0.0" + + +# -- General configuration ---------------------------------------------------- + +# Add any paths that contain templates here, relative to this directory. +# templates_path = ["_templates"] + +# Add any Sphinx extension module names here, as strings. +# They can be extensions coming with Sphinx (named "sphinx.ext.*") +# or your custom ones. +extensions = [ + "myst_parser", + "sphinx_copybutton", + "sphinx_design", + "sphinxext.opengraph", +] + + +# If true, the Docutils Smart Quotes transform, originally based on SmartyPants +# (limited to English) and currently applying to many languages, will be used +# to convert quotes and dashes to typographically correct entities. +# Note to maintainers: setting this to `True` will cause contractions and +# hyphenated words to be marked as misspelled by spellchecker. +smartquotes = False + +# The name of the Pygments (syntax highlighting) style to use. +# pygments_style = "sphinx.pygments_styles.PyramidStyle" +pygments_style = "sphinx" + +# Options for the linkcheck builder +# Ignore localhost +linkcheck_ignore = [ + r"http://127.0.0.1", + r"http://localhost", + # Ignore links to static files + r"/_static", + # Ignore pages that require authentication + r"https://github.com/kitconcept/volto-light-theme/issues/new", # requires auth + # Ignore github.com pages with anchors + r"https://github.com/.*#.*", + # Ignore other specific anchors +] +linkcheck_anchors = True +linkcheck_timeout = 5 +linkcheck_retries = 1 + +# The suffix of source filenames. +source_suffix = { + ".md": "markdown", + ".bugfix": "markdown", + ".breaking": "markdown", + ".documentation": "markdown", + ".feature": "markdown", + ".internal": "markdown", +} + +# The master toctree document. +master_doc = "index" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +suppress_warnings = [ + # "toc.excluded", # Suppress `WARNING: document isn't included in any toctree` + "toc.not_readable", # Suppress `WARNING: toctree contains reference to nonexisting document 'news*'` +] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = "plone_sphinx_theme" +html_logo = "_static/logo.svg" +html_favicon = "_static/favicon.ico" +html_theme_options = { + "article_header_start": ["toggle-primary-sidebar"], + "extra_footer": """

The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see https://plone.org/foundation/logo. All other trademarks are owned by their respective owners.

+

Pull request previews by Read the Docs.

""", + "footer_end": ["version.html"], + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/plone/volto", + "icon": "fa-brands fa-square-github", + "type": "fontawesome", + "attributes": { + "target": "_blank", + "rel": "noopener me", + "class": "nav-link custom-fancy-css", + }, + }, + { + "name": "Mastodon", + "url": "https://plone.social/@plone", + "icon": "fa-brands fa-mastodon", + "type": "fontawesome", + "attributes": { + "target": "_blank", + "rel": "noopener me", + "class": "nav-link custom-fancy-css", + }, + }, + { + "name": "Twitter", + "url": "https://twitter.com/plone", + "icon": "fa-brands fa-square-twitter", + "type": "fontawesome", + "attributes": { + "target": "_blank", + "rel": "noopener me", + "class": "nav-link custom-fancy-css", + }, + }, + ], + "logo": { + "text": "@kitconcept/volto-light-theme Documentation", + }, + "navigation_with_keys": True, + "path_to_docs": "docs", + "repository_branch": "main", + "repository_url": "https://github.com/kitconcept/volto-light-theme/tree/main/", + "search_bar_text": "Search", # TODO: Confirm usage of search_bar_text in plone-sphinx-theme + "use_edit_page_button": True, + "use_issues_button": True, + "use_repository_button": True, +} + +# Announce that we have an opensearch plugin +# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_use_opensearch +html_use_opensearch = "https://volto-light-theme.readthedocs.io/" # TODO: Confirm usage of opensearch in theme + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = "%(project)s v%(release)s" % {"project": project, "release": release} + +html_css_files = ["custom.css", ("print.css", {"media": "print"})] + +# If false, no index is generated. +html_use_index = True + +html_extra_path = [ + "robots.txt", +] + +html_static_path = [ + "_static", +] + + +# -- Options for MyST markdown conversion to HTML ----------------------------- + +# For more information see: +# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html +myst_enable_extensions = [ + "deflist", # Support definition lists. + # https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists + "linkify", # Identify "bare" web URLs and add hyperlinks. + "colon_fence", # You can also use ::: delimiters to denote code fences,\ + # instead of ```. + "html_image", # For inline images. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#html-images +] + + +# -- Intersphinx configuration ---------------------------------- + +# This extension can generate automatic links to the documentation of objects +# in other projects. Usage is simple: whenever Sphinx encounters a +# cross-reference that has no matching target in the current documentation set, +# it looks for targets in the documentation sets configured in +# intersphinx_mapping. A reference like :py:class:`zipfile.ZipFile` can then +# linkto the Python documentation for the ZipFile class, without you having to +# specify where it is located exactly. +# +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html +# +intersphinx_mapping = { + "plone": ("https://6.docs.plone.org/", None), +} + + +# -- OpenGraph configuration ---------------------------------- + +ogp_site_url = "https://volto-light-theme.readthedocs.io/" +ogp_description_length = 200 +ogp_image = ( + "https://volto-light-theme.readthedocs.io/en/latest/_static/Plone_logo_square.png" +) +ogp_site_name = "@kitconcept/volto-light-theme Documentation" +ogp_type = "website" +ogp_custom_meta_tags = [ + '', +] diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..123b9387 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,137 @@ +--- +myst: + html_meta: + "description": "How to contribute to Volto Light Theme" + "property=og:description": "How to contribute to Volto Light Theme" + "property=og:title": "Contributing" + "keywords": "Volto Light Theme, Contributing, Makefile, make, lint, format, i18n, tests, unit, Cypress, acceptance" +--- + +# Contributing + +This add-on is developed in isolation, using a new approach with pnpm workspaces, the latest `mrs-developer`, and other Volto core improvements. +For this reason, it only works with pnpm and Volto 18, but it does not mean that the add-on will only work in 18. + + +## Development requirements + +- Volto 18 +- pnpm as package manager + + +## Make convenience commands + +Run `make help` to list the available commands. + +```text +help Show this help +install Installs the add-on in a development environment +start Starts Volto, allowing reloading of the add-on during development +build Build a production bundle for distribution of the project with the add-on +build-deps Build dependencies +i18n Sync i18n +ci-i18n Check if i18n is not synced +format Format codebase +lint Lint, or catch and remove problems, in code base +release Release the add-on on npmjs.org +release-dry-run Dry-run the release of the add-on on npmjs.org +test Run unit tests +ci-test Run unit tests in CI +backend-docker-start Starts a Docker-based backend for development +storybook-start Start Storybook server on port 6006 +storybook-build Build Storybook +acceptance-frontend-dev-start Start acceptance frontend in development mode +acceptance-frontend-prod-start Start acceptance frontend in production mode +acceptance-backend-start Start backend acceptance server +ci-acceptance-backend-start Start backend acceptance server in headless mode for CI +acceptance-test Start Cypress in interactive mode +ci-acceptance-test Run cypress tests in headless mode for CI +acceptance-a11y-frontend-prod-start Start a11y acceptance frontend in prod mode +ci-acceptance-a11y-backend-start Start acceptance a11y server in CI mode (no terminal attached) +acceptance-a11y-test Start a11y Cypress in interactive mode +ci-acceptance-a11y-test Run a11y cypress tests in headless mode for CI +``` + + +## Development environment setup + +Install package requirements with the following commands. + +```shell +pnpm i +make install +pnpm i +``` + +### Start developing + +In one terminal session, start the backend server. + +```shell +make start-backend-docker +``` + +In a second terminal session, start the frontend server. + +```shell +pnpm start +``` + + +## Lint + +To lint the code—that is, to preview formatting suggestions of the code through ESlint, Prettier, and Stylelint—use the following command. + +```shell +make lint +``` + + +## Format + +To format the code—that is, actually rewrite it through ESlint, Prettier, and Stylelint—use the following command. + +```shell +make format +``` + + +## i18n + +Extract the i18n messages to locales. + +```shell +make i18n +``` + + +## Unit tests + +Run unit tests. + +```shell +make test +``` + + +## Run Cypress tests + + + +In one terminal session, start the frontend server in dev mode. + +```shell +make start-test-acceptance-frontend-dev +``` + +In a second terminal session, start the backend acceptance server. + +```shell +make start-test-acceptance-server +``` + +In a third terminal session, start the Cypress interactive test runner. + +```shell +make test-acceptance +``` diff --git a/docs/feature-flags.md b/docs/feature-flags.md new file mode 100644 index 00000000..92e0c8b4 --- /dev/null +++ b/docs/feature-flags.md @@ -0,0 +1,63 @@ +--- +myst: + html_meta: + "description": "Feature flags" + "property=og:description": "Feature flags" + "property=og:title": "Feature flags" + "keywords": "Volto Light Theme, Feature Flags, fat menu, siteLabel, intranetHeader" +--- + +# Feature flags + +Volto Light Theme has the following feature flags that you can enable or disable. + + +## Enable fat menu + +```{versionadded} 2.0.0 +``` + +Since 2.0.0, the light theme has a fat menu, located below the main site sections. +You can trigger it by clicking on one of the main site sections. +It's behind a feature flag, as configured as an opt-out by default. + +```js +config.settings.enableFatMenu = true; +``` + + +## Show `siteLabel` + +To show a label on top of the site, you can pass a label name to the `siteLabel` property. + +```js +config.settings.siteLabel = 'Plone Intranet'; +``` + +If you want a translatable label, then you must define a translation object in the `defineMessages` function, provided by [`react-intl`](https://www.npmjs.com/package/react-intl). + +You will need to add the following code snippets in your add-on's {file}`index.js` file. +If you don't have an add-on, then you can also add them in your {file}`config.js` file in root of your frontend folder. + +```js +import { defineMessages } from 'react-intl'; + +defineMessages({ + siteLabel: { + id: 'siteLabel', + defaultMessage: ' ', + }, +}); +``` + +Then add the translation you want in your `locale` file. + + +## Show `intranetHeader` + +We have a totally different header for intranet sites. +If you want that, you can enable it by passing the `intranetHeader` property. + +```js +config.settings.intranetHeader = true; +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..733583ab --- /dev/null +++ b/docs/index.md @@ -0,0 +1,168 @@ +--- +myst: + html_meta: + "description": "Volto Light Theme by kitconcept" + "property=og:description": "Volto Light Theme by kitconcept" + "property=og:title": "Volto Light Theme by kitconcept" + "keywords": "Volto Light Theme, kitconcept, Volto, theme, React" +--- + +# Volto Light Theme by kitconcept + +[![NPM](https://img.shields.io/npm/v/@kitconcept/volto-light-theme.svg)](https://www.npmjs.com/package/@kitconcept/volto-light-theme) +[![Build Status](https://github.com/kitconcept/volto-light-theme/actions/workflows/code.yml/badge.svg)](https://github.com/kitconcept/volto-light-theme/actions) +[![Build Status](https://github.com/kitconcept/volto-light-theme/actions/workflows/unit.yml/badge.svg)](https://github.com/kitconcept/volto-light-theme/actions) +[![Build Status](https://github.com/kitconcept/volto-light-theme/actions/workflows/acceptance.yml/badge.svg)](https://github.com/kitconcept/volto-light-theme/actions) + +![kitconcept GmbH](https://raw.githubusercontent.com/kitconcept/volto-blocks/master/kitconcept.png) + +## Vision + +The main vision of the Volto Light Theme (VLT) is to serve as a foundation for kitconcept's future projects, following the release of Plone 6. +It incorporates feedback from the company's clients and Plone community from the last few years of projects and the success stories in the UI/UX side. +It aims to be future-proof, keeping it aligned with the upcoming Volto and Plone 7 vision in terms of theming strategy decided by the Plone community. + +````{card} +```{image} /_static/volto-light-theme.png +:alt: Volto Light Theme screen shot +:target: /_static/volto-light-theme.png +``` ++++ +_Volto Light Theme_ +```` + + +## Requirements and specifications + +Volto Light Theme sets the following requirements and specifications for its development. + + +### Do not use any Semantic UI component or styling + +Semantic UI as a design component system is deprecated in Volto 18 and will be removed in Plone 7. +In preparation for this, VLT uses no Semantic UI component, nor any related styling (`.ui.XXX`). + +The Plone 7 strategy includes the following principles. + +- Provide a very basic, structural, vanilla collection of components to build upon theming and the CMS UI, as implemented in [`@plone/components`](https://github.com/plone/volto/tree/main/packages/components). +- These components will be based upon a headless component system [React Aria Components](https://react-spectrum.adobe.com/react-aria/components.html). +- Volto projects can be themed using `@plone/components` as a base, or use a completely different design or component system of the developer's or integrator's choice. + + +### Volto components shadowing (`customizations`) use case and best practice + +If possible, we will switch to Semantic UI-less components when `@plone/components` is ready, especially if the elements that we customize are clearly theme-related, such as the header, footer, and other theme elements. +When other Volto customizations are not clearly part of the theme, such as the Search block, it's fine to stick with what the original uses, even Semantic UI. +When Volto makes the switch in the future, we should adapt all the customizations to match the one in the Volto core. +VLT takes the approach of using a proxy to a component of the `components` folder. +This way it's easier to keep track of changes, and another add-on can customize further the VLT component, not the original Volto customization. + + +### It should use kitconcept's layout used in FZJ/DLR projects + +Starting with FZJ/DLR projects, we've been trying a new concept in layout for Volto. +This new layout uses three widths for the content elements: + +- Narrow (text) +- Default (blocks) +- Layout (main screen elements such as Header, Footer) + +The Layout sized elements snap to 1440px. +The breakpoints are also different from default Volto. +This new layout uses mixins and CSS that can be found in {file}`layout.less` in the {file}`src/theme` folder. +It leverages container queries for managing the layout styling. + + +### Organization of the files + +We will start organizing the files in the root of the {file}`theme` folder, to differentiate them from a normal "Semantic UI" theme. +Take a look at the current state. +We will follow this convention: + +- One file per component or block. +- Use the Volto theme facility using the provided SCSS escape hatch, so other add-ons can hook into it. +- The styling is centralized in {file}`main.scss`, and the rest of the files are loaded from there. + + +## Why a headless component system? + +https://medium.com/@nirbenyair/headless-components-in-react-and-why-i-stopped-using-ui-libraries-a8208197c268 + + +## Vertical spacing block model (v2) + +This theme has the concept of block "grouping", given two consecutive blocks with the same styling block wrapper property `backgroundColor`. +You have to add this property to your blocks in your blocks code. +This add-on customizes the {file}`RenderBlocks.jsx` component to do so. + +The wrappers have the class names `blocks-group-wrapper`, and the name of the background color, such as `grey`, defaulting to `transparent` if no `backgroundColor` property is set in the styling block wrapper in the block. + +**Disclaimer**: This might change in the near future, since we are developing a new integral Block Model for VLT and Volto. + + +### Vertical spacing rules + +The following main rules specification applies to the theme. + +- On each change of color, a vertical padding (both `padding-bottom` and `padding-top`) of `80px` defined by the main variable `$color-block-change-vertical-spacing`. +- The default bottom margin is defined with the main variable `$block-vertical-space` and set by default to `25px`. +- [grid] Vertical spacing for grids should be `80px` for both top and bottom, even if the previous and next blocks are of the same color. +- [grid+grid] When two grids happen side by side and are of the same color, it should be equal to the grid gap. + Thus, it's set to `@gutterWidth`, and currently `1rem`. + It has to be adjusted with a bit of negative margin to cancel the current inner padding in grid cells. +- [grid+grid] Grids columns belonging to the same grid and same color in small mobile viewports. + They should be closer to match the other adjacent ones, so they seem to belong to the same grid set. +- [footer] The footer has a top vertical spacing of `80px`. +- [teasers] The last teaser, except if the following is a button, does _not_ have a line at the bottom. +- [listing] The last listing, except if the following is a button, does _not_ have a line at the bottom. +- [listing] After two consecutive listings, the vertical spacing should be `200px`. +- [text+button] If there's a text and a button, then the vertical spacing between them is `60px`. +- [image+separator-block] If after an image comes a separator block, the vertical spacing between them is `40px`. + + +### Media queries vs. container queries + +We use media queries when the styling is generic enough to apply only to the view. + +We use container queries when we care explicitly about how the styles are applied in edit mode, and we want the content area to behave 1:1 with the view mode. + +This is because the container queries allow us to abstract the width from the sidebar and toolbar in edit mode, showing the content area as it will be in that size, in view mode. + +**Remember**: The margins in responsive layouts are handled with container queries in {file}`layout.scss`. +So everything related to that, goes like it works in there, with container queries. +See implementations for details in case you need it. + + +## Specification + +`@kitconcept/volto-light-theme` works with the following Plone Blocks: + +- [Grid-Block](https://www.npmjs.com/package/@kitconcept/volto-blocks-grid) +- [Teaser-Block](https://www.npmjs.com/package/@kitconcept/volto-blocks-grid) +- [Slider-Block](https://www.npmjs.com/package/@kitconcept/volto-slider-block) +- [Button-Block](https://www.npmjs.com/package/@kitconcept/volto-button-block) +- [Separator-Block](https://www.npmjs.com/package/@kitconcept/volto-separator-block) +- [Heading-Block](https://www.npmjs.com/package/@kitconcept/volto-heading-block) +- [Introduction-Block](https://www.npmjs.com/package/@kitconcept/volto-introduction-block) +- [Accordion-Block](https://www.npmjs.com/package/@eeacms/volto-accordion-block) + +and the following add-ons: + +- [DSGVO-Banner](https://www.npmjs.com/package/@kitconcept/volto-dsgvo-banner) + + +## Block Model v3 + +We are working at the same time on a new spec for blocks: [The Block Model v3](./block-model-v3.md). + + +```{toctree} +:maxdepth: 1 +install +feature-flags +contributing +upgrade-guide +block-model-v3 +compatibility +releases +``` diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 00000000..e63595a4 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,72 @@ +--- +myst: + html_meta: + "description": "How to install Volto Light Theme" + "property=og:description": "How to install Volto Light Theme" + "property=og:title": "Install" + "keywords": "Volto Light Theme, install" +--- + +# Install + +Along with the `@kitconcept/volto-light-theme` package, you should also install in your setup the following add-ons. + +```json + "dependencies": { + "@eeacms/volto-accordion-block": "^10.4.6", + "@kitconcept/volto-button-block": "^3.0.2", + "@kitconcept/volto-dsgvo-banner": "^2.3.2", + "@kitconcept/volto-heading-block": "^2.4.0", + "@kitconcept/volto-highlight-block": "^4.0.0", + "@kitconcept/volto-introduction-block": "^1.0.0", + "@kitconcept/volto-separator-block": "^4.1.2", + "@kitconcept/volto-slider-block": "^6.3.1", + "@kitconcept/volto-light-theme": "^5.0.1", + } +``` + +```{note} +The version numbers of these add-ons are merely illustrative, but current as of 2024-11-04. +You should update the versions to their latest. +``` + +This theme won't install the add-ons for you, as they are declared as `peerDependencies`. +This is because the theme won't have to force you to use any specific add-on version, and avoids package hoisting issues. + +In your project or policy add-on {file}`package.json` you should declare all of them as Volto add-ons + +```json +"addons": [ + "@eeacms/volto-accordion-block", + "@kitconcept/volto-button-block", + "@kitconcept/volto-heading-block", + "@kitconcept/volto-introduction-block", + "@kitconcept/volto-highlight-block", + "@kitconcept/volto-separator-block", + "@kitconcept/volto-light-theme", + "your_policy_addon_here" +], +``` + +Your policy add-on should be the last one, so that it overrides any previous ones. +`@kitconcept/volto-light-theme` should be the second-last, placed immediately before your policy add-on. + +Then, declare the theme in your project {file}`package.json`. + +```json +"theme": "@kitconcept/volto-light-theme", +``` + +Alternatively, you can declare it in your project's {file}`volto.config.js`. + +```js +const addons = []; +const theme = '@kitconcept/volto-light-theme'; + +module.exports = { + addons, + theme, +}; +``` + +Although you can specify your project add-ons in {file}`volto.config.js`, sometimes it is better to have them all in one place in your policy add-on for portability. diff --git a/docs/releases.md b/docs/releases.md new file mode 100644 index 00000000..bbd2de63 --- /dev/null +++ b/docs/releases.md @@ -0,0 +1,35 @@ +--- +myst: + html_meta: + "description": "Volto Light Theme releases" + "property=og:description": "Volto Light Theme releases" + "property=og:title": "Releases" + "keywords": "Volto Light Theme, Releases" +--- + +# Releases + +The releases follow a semantic versioning model. + +## Definition of breaking change + +In general, the same definitions and rules of a breaking change in Volto releases apply to VLT. +However, in VLT we add an extra exception. +The vertical spacing is carefully curated and considered an important feature of the theme. +Because of that, changes and improvements in the vertical spacing are _not_ considered breaking changes. +They will be noted properly in the change log. + + +## Release process + +To release a full version, run the following command. + +```shell +make release +``` + +To release a release candidate (rc) version, run the following command. + +```shell +make release-rc +``` diff --git a/docs/robots.txt b/docs/robots.txt new file mode 100644 index 00000000..bed8d1f4 --- /dev/null +++ b/docs/robots.txt @@ -0,0 +1,8 @@ +# Disallow all user agents from the following directories and files +User-agent: * +Disallow: /_sources/ +Disallow: /.doctrees/ +Disallow: /*.txt$ +Disallow: /.buildinfo$ +Disallow: /objects.inv$ +Sitemap: https://volto-light-theme.readthedocs.io/en/latest/sitemap.xml diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md new file mode 100644 index 00000000..adbbaa52 --- /dev/null +++ b/docs/upgrade-guide.md @@ -0,0 +1,120 @@ +--- +myst: + html_meta: + "description": "Volto Light Theme upgrade guide" + "property=og:description": "Volto Light Theme upgrade guide" + "property=og:title": "Upgrade guide" + "keywords": "Volto Light Theme, upgrade guide" +--- + +# Upgrade guide + +## volto-light-theme 6.0.0 + +### Color definitions + +The VLT has migrated to use the standardized color definitions in Volto. +These new definitions use CSS properties that are injected at runtime in the right places, so your CSS can adapt to use them in a generic way. +The resultant CSS is simpler, and there's no need to define class names for each color definition. +Read more about them in: https://6.docs.plone.org/volto/development/color-picker-widget.html?highlight=color#custom-css-properties-as-color-definitions + +The new color definitions are no longer hardcoded, and now they are stored in `config.settings.backgroundColors`. + +```ts +config.settings.backgroundColors = [ + { + style: { + '--background-color': 'transparent', + }, + name: 'transparent', + label: 'Transparent', + }, + { + style: { + '--background-color': '#ecebeb', + }, + name: 'grey', + label: 'Grey', + }, +]; +``` + +```css +.block.teaser { + background-color: var(---background-color, #fff) +} +``` + +If you extended or modified the default background colors in VLT, you need to move the colors that you are using accordingly to the new definitions. +Once the new definitions are in place, there is a content reducer transform in place that will convert the blocks on the fly. +Whenever you save an object, the object will be saved using the new styling. +Make sure that you use the same `name` as before when you update your color definitions. + + +### Block widths + +VLT has started to use the standard block width definition as well. +It's stored in `config.settings.blocksWidths`. +It uses a new widget component that would be ported to Volto core as soon as it's ready. +This component saves the value of the custom CSS property `--block-width` as a StyleWrapper value, so it can be used later when the StyleWrapper injects it in the block (or component) markup. + + +## volto-light-theme 5.0.0 + +The requirements for VLT have changed: + +| VLT version | Volto version | +|-------------|---------------| +| 3.x.x | >= Volto 17.0.0-alpha.16 | +| 4.x.x | < Volto 17.18.0 | +| 5.x.x | >= Volto 17.18.0 or >=Volto 18.0.0-alpha.36 | + + +## volto-light-theme 4.0.0 + +The tabbing order in the top header was fixed for accessibility concerns. +It modifies the underlying HTML, moving from the top header to the bottom, and modifies the CSS to adjust. + +The `MobileNavigation` component was updated to be more easily customizable. +The component can now handle infinite navigation depth instead of only three levels, if configured to do so. +The Burger Menu can now be easily customized by overriding the new {file}`MobileNavigationToggler.jsx` file. + + +## volto-light-theme 3.0.0 + +### Blocks background colors go full width + +The background colors previously snapped to 1440px. +From 3.0.0-alpha.0 onward, this changed to be unconstrained by default, and expands to the end of the horizontal viewport. + + +### Upgraded support for volto-slider-block 6.0.0 + +VLT upgraded the dependency on `@kitconcept/volto-slider-block` to use `6.0.0`. + +This is a drop-in replacement, so no action is required for the existing slider blocks you may already have in your sites. +However, the CSS classes of the structural slider block elements changed in this version. +The inner (visible objects) CSS classes remain unchanged. +If you have customized them in your project, you may have to update them, although the structural class names are rarely customized aside from vertical spacing properties. +They are mapped 1:1 with the previous ones, following this table correspondence: + +| Old className | New className | +| --------------- | ---------------- | +| slick-slider | slider-wrapper | +| slick-list | slider-viewport | +| slick-track | slider-container | +| slick-slide | slider-slide | +| slick-arrow | slider-button | +| slick-prev | slider-button-prev | +| slick-next | slider-slide-next | +| slick-next | slider-slide-next | +| slick-dots | slider-dots | +| slick-dot | slider-dot | + +For more information, check the https://github.com/kitconcept/volto-slider-block/blob/main/README.md and [#288](https://github.com/kitconcept/volto-light-theme/pull/288). + + +### Language switcher shows the two-letter language code + +The default in Volto is to show the full name of the language in the language switcher. +VLT now shows only the two-letter language code. diff --git a/packages/volto-light-theme/news/423.documentation b/packages/volto-light-theme/news/423.documentation new file mode 100644 index 00000000..a89b3621 --- /dev/null +++ b/packages/volto-light-theme/news/423.documentation @@ -0,0 +1 @@ +Add standard documentation @sneridagh diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 00000000..cb08ab71 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,8 @@ +# requirements.txt +linkify-it-py +myst-parser +plone-sphinx-theme +sphinx-autobuild +sphinx-copybutton +sphinx-design +sphinxext-opengraph