Created by: ffoodd
Fixes #30918 (closed), fixes #24807 (closed), fixes #27783 (closed), fixes #31845 (closed)
Preview — Examples — cheatsheet — RTL cheatsheet
Todo
Beta 2
-
Move cheatsheet from examples to main docs -
Allow main docs to be passed a direction
in the front matter and have that automatically toggle LTR to RTL CSS inclusion -
The above items should resolve most of this, but... De-dupe the RTL CSS once moved -
Convert page content to Markdown -
And https://github.com/twbs/bootstrap/pull/30980#issuecomment-737096962
Cheatsheet
-
use button
s in cheatsheet side navigation, as it's been done in our main docs recently -
Fix the sticky components title covering the page content -
Fix floating labels example (remove row) -
Make the header a little less huge -
check and update translations in examples and cheatsheet
Docs
-
check again I didn't break @mdo's changes to the docs -
ensure there's no missing occurrences of our old-fashioned classes (will take care of that when we'll be about to merge) -
Fix alignment utilities breakage https://deploy-preview-30980--twbs-bootstrap.netlify.app/docs/5.0/utilities/position/ -
Search docs for left
andright
in case we missed something
Done
-
add RTLCSS and dedicated scripts
Test cases
-
convert some example templates to dir="rtl"
—those on which direction makes a difference: -
add lang="ar"
(andhreflang="ar"
in examples list) -
translate them to Arabic. (need help) - I used both Google Translate and an Arabic Lorem Ipsum generator—however I don't expect those to be either accurate or even good. I'll try to find proof-reader for this.
-
Kitchen sink of sorts: all our components in one page, with its RTL counterpart. Maybe use some kind of Hugo shortcode to ease this?- The Cheatsheet is available, next to the Migration page: https://deploy-preview-30980--twbs-bootstrap.netlify.app/docs/5.0/examples/cheatsheet/
- its RTL counterpart exists (https://deploy-preview-30980--twbs-bootstrap.netlify.app/docs/5.0/examples/cheatsheet-rtl/), however it's not translated and it seems odd to try: I'll ask about it in a comment.
-
missing JavaScript for components, -
and the directional dropdowns, popovers and tooltips to add.
-
Update → Cheatsheet examples, to ease counterpart and translations: -
translate RTL cheatsheet to Arabic -
bulletproof testing, with the help of RTL Styling 101—focusing mainly on Things that might not work and RTL design considerations for common components - See the "Spotted bugs" comment above
-
check with everything enabled (shadows, gradients, etc.)
Spotted bugs
-
carousel arrows -
Card link isn't aligned properly. The margin-right: 1rem;
should bemargin-left: 1rem;
(see comment below). -
disable word-break
on RTL?- "Line break" section in RTL Styling 101 — I opened an issue to mention other word-breaking properties
- see comment below
- This required to introduce a new
rtl
boolean property in our Utility API, to add an RTLCSSremove
directive around the utility.
-
email and phone fields: it looks content-related to me, but we may have to provide a way to handle this. -
Dropdowns, tooltips and popovers: their left/right variants aren't flipped for now, and ignored from RTLCSS (see comment below). -
the default dropdown should follow the reading direction (Left/LTR and Right/RTL)
- RTLCSS's Bootstrap fork (4.2.1) did something interesting
-
-
rename variants for dropdowns, tooltips and popovers, in both SCSS and JS (eg. constants). I guess most data
attributes would keepright
andleft
since it's Popper based, but the Bootstrap layout could still usestart
andend
to stay consistent. -
Breadcrumb separator now has a second variable $breadcrumb-divider-flipped
to allow different separator for each direction.
Documentation
-
Docs page (perhaps under Getting Started or Customize) to document how we build our RTL dist files. This should include how to build with these files (which is likely a small modification from the Customize docs) and edge cases -
Breadcrumb separator: our current is a /: it's not changed to backslash (should it?) - moreover, this separator can be overridden to use an icon (typically, an arrow) which wouldn't be flipped: should we flip the separator, no matter what it is?
- https://rtlstyling.com/posts/rtl-styling#breadcrumbs
- see comment below
-
switching font-family
for RTL (Boosted switches from Helvetica Neue to Helvetica Neue Arabic, for example) -
drop→ Irrelevant, we'll simply add RTL Styling 101 in additional resources.letter-spacing
if any ( https://www.rtlstyling.com/posts/rtl-styling/#1.-letter-spacing) -
how-tos with RTLCSS
-
-
update RTL examples' screenshot -
mention rtl: {boolean}
in Utility API doc -
mention RTL files in "Introduction", "downloads" & "Getting started" pages, at least
Chore things
-
add files to SRI hashes and docs' _config.yml
-
#31210 — consider renaming things, ala Logical properties—to prevent .float-left { float: right; }
. It would also help to switch to logical properties one day (when dropping Legacy Edge, v6 or tomorrow with #30986 ?) -
add RTL files to Bundlewatch -
double check the css-rtl
task: something feels weird when it comes to start the docs, since it builds the dist then post-processes it for RTL. -
Missing a way to correctly handle modal's padding in two ways. I fixed a case but I guess there's more… - and it will obviously require new test, I guess?
-
proof-read JS changes: I added a utility to check if document is using dir="rtl"
and calling it where appropriate to toggle right / left. -
double-check package.json
changes:- I duplicated
css-minify
to prevent a hundreds cols long script, but it's basically the same, split on two parts (standards + RTL) - I added a watcher for
dist/css/
to reload when RTL files are compiled again (since they're not compiled from our sources but from our dist files)
- I duplicated
-
fix sourcemaps for RTL dist files - FWIW, sourcemaps are fine: there's a single path ending URL encoded, but it's not part of our sources:
%3Cinput%20css%202%3E
- I think it relates to the
/*rtl:raw*/
directive, used for[type="email"]
for example; - Other
/* rtl:* */
directives are correctly mapped to their sources. - Opened an issue upstream to have some better understanding.
- FWIW, sourcemaps are fine: there's a single path ending URL encoded, but it's not part of our sources:
-
(optional) run examples CSS through RTLCSS (dashboard, carousel, blog) to use a single source for both LTR & RTL -
@XhmikosR I managed to make it work as intended, however I'm stuck with setting the full output path since glob patterns don't seem to work here (so we have
/5.0/
) in--dir
and--base
).
-
@XhmikosR I managed to make it work as intended, however I'm stuck with setting the full output path since glob patterns don't seem to work here (so we have
-
check new examples' screenshot (old logo?) -
make a new dist PR separately before we land this one (#32216)
Questions
-
About the new Cheatsheet example: should we add introduction text before each component or section?→ Probably not, since it's mostly a detailed view not meant to replace docs. -
I used RTLCSS block-level syntax for directives, but RTLCSS' fork used property-level syntax. Block-level is lighter to output and faster to parse, but make it less obvious of what is important to ignore for RTL. Should I move to property-level syntax?→ Switched to property-level syntax, as argued in comments.
References
- RTLCSS documentation
- RTLCSS's Bootstrap fork
-
Boosted scripts (
css-compile-rtl
anddocs-rtl
mostly) - RTL Styling 101
Related
RTL concerns
#28797 (closed) #28238 (closed) #24807 (closed) #27123 (closed) #27122 (closed) #26879 (closed) #26818 (closed) #19545 (closed) #26299 (closed) #25422 (closed) #24662 (closed) #23703 #24332 (closed) #23117 (closed) #22708 #22137 (closed) #21619 (closed) #21180 (closed) #20293 (closed) #19555 (closed) #20075 (closed) #19787 (closed) #19703 (closed) #19668 (closed) #19643 (closed) #19545 (closed) #19379 (closed) #18184 (closed) #17595 (closed) #16455 (closed) #16419 (closed) #15717 (closed) #15700 (closed) #15509 (closed) #15479 (closed) #15433 (closed) #14717 (closed) #14510 (closed) #13564 (closed)
Kitchen sink of sorts
#18645 (closed) #27783 (closed) #21209 (closed) #17423 (closed)