feat(docs): add RTL decorator by rubencarvalho · Pull Request #6188 · adobe/spectrum-web-components

rubencarvalho · 2026-04-17T11:40:30Z

Description

Adds a dedicated Direction Storybook toolbar control (auto / LTR / RTL) alongside the existing Language control. Direction resolution:

Auto — follows locale (RTL for Arabic, Hebrew, and Farsi when applicable; otherwise LTR).
LTR / RTL — explicit override, independent of language (so typography/font kit can stay on one locale while layout direction is forced).

The withLanguageWrapper decorator applies the resolved direction on the preview root using both:

dir on document.documentElement (semantic / bidi), and
direction via inline CSS on the same element (explicit visual direction).

context.globals.resolvedTextDirection is set so stories or tooling can read the final ltr | rtl value. The globalsUpdated listener was updated so direction changes apply even when the decorator does not re-run (e.g. some docs flows).

Motivation and context

Language alone implied RTL for some locales, which made it awkward to test LTR vs RTL without changing locale, especially when pairing a specific font/locale with a fixed reading direction. A separate Direction control fixes that.

This also unblocks Chromatic VRT: you can template permutations (e.g. theme × scale × explicit LTR/RTL) without relying on switching to an RTL locale only to get dir/layout. Stories or Chromatic configuration can key off globals.textDirection / resolvedTextDirection.

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed the Accessibility Practices for this feature, see: ARIA Practices (toolbar sets document dir; no new interactive component in the library.)
I have added automated tests to cover my changes.
I have included a well-written changeset if my change needs to be published.
I have included updated documentation if my change required it (consider a short note in the Fonts / customization guide about Direction vs Language).

Reviewer's checklist

Manual review test cases

Direction toolbar + document root
1. Open any 2nd-gen Storybook story.
2. Set Language to English and Direction to RTL.
3. Inspect <html>: expect dir="rtl" and inline direction: rtl (or equivalent).
4. Set Direction to LTR; expect dir="ltr" and LTR CSS.
Auto follows locale
1. Set Direction to Auto.
2. Switch Language between English and Arabic (or Hebrew).
3. Expect RTL when locale is RTL and LTR for English, without manual Direction overrides fighting Auto.

changeset-bot · 2026-04-17T11:40:33Z

⚠️ No Changeset found

Latest commit: c0b6d22

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2026-04-17T11:46:09Z

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-6188

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

pfulton

Looks great. I clicked-through to the deployed Storybook instance and was able to follow the testing instructions. Everything worked as expected.

Thanks for taking care of this!

Rajdeepc · 2026-04-19T13:26:56Z

+    return textDirection;
+  }
+
+  return RTL_LANGS.has(String(lang ?? 'en-US')) ? 'rtl' : 'ltr';


?? only short‑circuits on null | undefined. When lang === false this evaluates to String(false) === 'false', which never matches RTL_LANGS. You get LTR for the right reason by accident. You can use lang || 'en-US' to mirror the convention used in applyLanguageAndFontKit (lang ? String(lang) : 'en-US')

Rajdeepc · 2026-04-19T13:29:14Z

-    context.globals.textDirection = isRTL ? 'rtl' : 'ltr';
+    // Keep an explicit, resolved direction available for stories.
+    const resolvedTextDirection = resolveTextDirection(lang, textDirection);
+    context.globals.resolvedTextDirection = resolvedTextDirection;


This can be an anti-pattern of mutating context.globals during render. If you want to keep this would you like to add a comment explaining the contract. I just want to avoid the future contributors to propagate this pattern.

You're right - no need for this now, so I removed it :)

Rajdeepc · 2026-04-19T13:31:10Z

+  root.setAttribute('dir', textDirection);
+  root.style.direction = textDirection;


dir="rtl" on an element already maps to direction: rtl via the UA stylesheet. This will add an inline specificity which can fight overrides further down. Can you show me an example where the dir attribute alone is not propagating?

miwha-adobe · 2026-04-20T18:56:50Z

+  lang: string | false,
+  textDirection: 'ltr' | 'rtl'
+): void {
  const langAttr = lang ? String(lang) : 'en-US';


nit: This could also be updated to lang || 'en-US', since the truthy path is always going to be a string.

Also what happens if you are passed a invalid lang string? I know this is just storybook, but we might want to consider some stronger type safety.

If we pass an invalid string here right now it will silently LTR. The set check is RTL_LANGS.has(String(lang || 'en-US')), so any string not in {'ar','fa','he'} → 'ltr'

Rajdeepc

Looks good!

feat(docs): add RTL decorator

dcd961e

rubencarvalho added Status:Ready for review PR ready for review or re-review. 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. labels Apr 17, 2026

rubencarvalho marked this pull request as ready for review April 17, 2026 16:35

rubencarvalho requested a review from a team as a code owner April 17, 2026 16:35

pfulton approved these changes Apr 17, 2026

View reviewed changes

Rajdeepc reviewed Apr 19, 2026

View reviewed changes

pfulton assigned pfulton and Rajdeepc Apr 20, 2026

rubencarvalho and others added 2 commits April 20, 2026 18:48

chore: address feedback

debb72f

Merge branch 'main' into ruben/gen2-storybbok-rtl

4d3bfc6

rubencarvalho requested a review from Rajdeepc April 20, 2026 17:30

miwha-adobe reviewed Apr 20, 2026

View reviewed changes

Rajdeepc approved these changes Apr 21, 2026

View reviewed changes

chore: address nit

c0b6d22

rubencarvalho enabled auto-merge (squash) April 21, 2026 11:55

rubencarvalho merged commit 2dcb68e into main Apr 21, 2026
29 of 31 checks passed

rubencarvalho deleted the ruben/gen2-storybbok-rtl branch April 21, 2026 12:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): add RTL decorator#6188

feat(docs): add RTL decorator#6188
rubencarvalho merged 4 commits intomainfrom
ruben/gen2-storybbok-rtl

rubencarvalho commented Apr 17, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Apr 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 17, 2026 •

edited

Loading

Uh oh!

pfulton left a comment

Uh oh!

Rajdeepc Apr 19, 2026

Uh oh!

rubencarvalho Apr 20, 2026

Uh oh!

Rajdeepc Apr 19, 2026

Uh oh!

rubencarvalho Apr 20, 2026

Uh oh!

Rajdeepc Apr 19, 2026

Uh oh!

rubencarvalho Apr 20, 2026

Uh oh!

miwha-adobe Apr 20, 2026

Uh oh!

Rajdeepc Apr 21, 2026

Uh oh!

Rajdeepc left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		root.setAttribute('dir', textDirection);
		root.style.direction = textDirection;

Conversation

rubencarvalho commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Author's checklist

Reviewer's checklist

Manual review test cases

Uh oh!

changeset-bot Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

Uh oh!

pfulton left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rajdeepc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rubencarvalho commented Apr 17, 2026 •

edited

Loading

changeset-bot Bot commented Apr 17, 2026 •

edited

Loading

github-actions Bot commented Apr 17, 2026 •

edited

Loading