From 4e9ffbfa6f9873025c8389c43348fd109669dc80 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Thu, 29 Feb 2024 10:37:08 -0500 Subject: [PATCH] Create a dedicated CSS file for customization When it comes to custom styling, basically we could just import a custom CSS file after the last existing `@import` on _components.pcss and put every custom stuff like CSS declarations and variables in it to let them override the inherited values in the way which the concept of CSS expects. In order to achieve it, this commit updates rethemendex.sh, so that any CSS files in _sc/ folder are excluded from being included to alphabetic sorting which causes cascading mess, ensuring _customization.pcss is imported at the end of the file. The obvious merit of doing so is that it will remove the burden of applying customization directly on the upstream CSS codebase fixing conflicts. Separating custom styles from the upstream codebase should also greatly reduce the manpower to rebase, without being worried about possible regressions. Doing so will also make it easier to fix the regressions on our codebase which the upstream project has not fixed yet. Additionally, it will make contributing easier for those who would like to contribute but are not familiar with the style codebase for SchildiChat, like me. Even if declarations are flagged with !important by the upstream to cover a new regression, it will be possible to override them with ours flagged with !important on our custom CSS files. The way in which the upstream project generates concatenated CSS files has been very stable (essentially same since at least 2018. See: https://github.com/matrix-org/matrix-react-sdk/commits/develop/res/css/rethemendex.sh), so we should be able to depend on the current way how it works for a reasonable time. --- res/css/_components.pcss | 3 +++ res/css/_sc/README.md | 21 +++++++++++++++++++++ res/css/_sc/_customization.pcss | 19 +++++++++++++++++++ res/css/rethemendex.sh | 12 +++++++++++- 4 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 res/css/_sc/README.md create mode 100644 res/css/_sc/_customization.pcss diff --git a/res/css/_components.pcss b/res/css/_components.pcss index 12d2457fc5d1..8ddcf474cf87 100644 --- a/res/css/_components.pcss +++ b/res/css/_components.pcss @@ -382,3 +382,6 @@ @import "./voice-broadcast/atoms/_VoiceBroadcastRecordingConnectionError.pcss"; @import "./voice-broadcast/atoms/_VoiceBroadcastRoomSubtitle.pcss"; @import "./voice-broadcast/molecules/_VoiceBroadcastBody.pcss"; + +/* Customization for SchildiChat */ +@import "./_sc/_customization.pcss"; diff --git a/res/css/_sc/README.md b/res/css/_sc/README.md new file mode 100644 index 000000000000..2305a6787eff --- /dev/null +++ b/res/css/_sc/README.md @@ -0,0 +1,21 @@ + + +# `_sc` folder for customization + +For customization, import a custom CSS file on `res/css/_sc/_customization.pcss` and put anything such as custom CSS declarations and variables in it to let them override the values inherited from the upstream. + +Please mind where to import a new CSS file. **Never sort the files alphabetically as it breaks how styles cascade.** diff --git a/res/css/_sc/_customization.pcss b/res/css/_sc/_customization.pcss new file mode 100644 index 000000000000..31ef3e71b5da --- /dev/null +++ b/res/css/_sc/_customization.pcss @@ -0,0 +1,19 @@ +/* +Copyright 2024 Suguru Hirahara + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +/* TODO: use @mixin or something for scoping once multiple CSS files are created + for customization in order to keep styling modular */ +/* Please mind where to import CSS files as it might affect how styles cascade. */ diff --git a/res/css/rethemendex.sh b/res/css/rethemendex.sh index 37090b96d8fb..db4b0db8c30c 100755 --- a/res/css/rethemendex.sh +++ b/res/css/rethemendex.sh @@ -8,8 +8,18 @@ cd `dirname $0` # we used to have exclude /themes from the find at this point. # as themes are no longer a spurious subdirectory of css/, we don't # need it any more. - find . -iname _\*.pcss | fgrep -v _components.pcss | LC_ALL=C sort | + # + # Exclude _sc/ folder dedicated for our own CSS files from being included + # to alphabetic sorting which causes cascading mess. Please note that CSS files + # inside the folder should be imported manually. + find . -iname _\*.pcss -not -path "./_sc/*" | fgrep -v _components.pcss | LC_ALL=C sort | while read i; do echo "@import \"$i\";" done + + # After the alphabetic sort conducted above, import the CSS file dedicated + # for customization to let declarations on the file override the styles + # specified by the upstream project. + echo "\n/* Customization for SchildiChat */" + echo "@import \"./_sc/_customization.pcss\";" } > _components.pcss