fix(combobox, breadcrumbs): propagate lang/dir for a single item's language without breaking layout

Previously, setting `lang`/`dir` on a slotted `<sp-menu-item>` (Combobox)
or `<sp-breadcrumb-item>` (Breadcrumbs) had no effect on the rendered
popover/overflow-menu counterpart, since both components synthesize new
elements from extracted data rather than reusing the originals.

- Combobox: forwards `lang`/`dir` from slotted items (or `.options` data)
  onto the rendered popover `<sp-menu-item>`, and now syncs the input's
  own `lang` to the committed option's language for correct pronunciation.
- Breadcrumbs: same propagation for the "More items" overflow menu.
- BreadcrumbItem: forwards `lang`/`dir` to `#item-link` only, so a single
  item's language does not flip its own layout or its separator's
  mirrored chevron. The separator now explicitly tracks the *ambient*
  direction (nearest ancestor `dir`, or the document default) instead of
  inheriting the host's own `dir` attribute via `:dir()`, including live
  updates when an ancestor's `dir` changes after mount, and across the
  shadow-root boundary for the overflow-menu wrapper item.

Along the way, worked around two non-obvious base-class behaviors that
caused regressions mid-fix: `SpectrumElement` overrides `dir` to return
computed CSS direction rather than the attribute (must read
`getAttribute('dir')` for authored values), and CSS `:dir()` resolves
directionality via the attribute chain, independent of the `direction`
property.

Adds Storybook stories (`languageOfParts` / `LanguageOfParts`) and test
coverage for each fix, each verified to fail without its corresponding
code change.

Jira: SWC-2359

Author: Michael Jordan

1st-gen/packages/breadcrumbs/src/BreadcrumbItem.ts

@@ -30,6 +30,30 @@ export interface BreadcrumbSelectDetail {
   value: string;
 }
 
+// Walks up through `parentElement`, crossing shadow-root boundaries via
+// `getRootNode().host` — needed because `Breadcrumbs.renderMenu()` places
+// an "is-menu" `BreadcrumbItem` inside its own shadow root rather than as
+// a light-DOM child, so a plain `parentElement` walk would stop there
+// without ever reaching `<sp-breadcrumbs>` itself.
+function* ancestorElements(start: Element): Generator<Element> {
+  let node: Node = start;
+  for (;;) {
+    const parent = (node as Element).parentElement;
+    if (parent) {
+      yield parent;
+      node = parent;
+      continue;
+    }
+    const root = node.getRootNode();
+    if (root instanceof ShadowRoot) {
+      yield root.host;
+      node = root.host;
+      continue;
+    }
+    break;
+  }
+}
+
 export class BreadcrumbItem extends LikeAnchor(Focusable) {
   public static override get styles(): CSSResultArray {
     return [styles, chevronStyles];
@@ -49,12 +73,40 @@ export class BreadcrumbItem extends LikeAnchor(Focusable) {
     return this.shadowRoot.querySelector('#item-link') as HTMLElement;
   }
 
+  // `renderLink()` and `renderSeparator()` bake this host's own `lang`/`dir`
+  // and the ambient `direction` into explicit attributes at render time.
+  // Neither `lang` nor `dir` is a reactive Lit property here, so — unlike
+  // plain CSS inheritance — none of that updates on its own if this host's
+  // own `lang`/`dir` change, or an ancestor's `dir` changes, after mount.
+  // Watching this host (for `lang`/`dir`) and every ancestor (for `dir`)
+  // keeps both cases live.
+  private readonly ancestorDirObserver = new MutationObserver(() =>
+    this.requestUpdate()
+  );
+
   override connectedCallback(): void {
     super.connectedCallback();
 
     if (!this.hasAttribute('role')) {
       this.setAttribute('role', 'listitem');
     }
+
+    this.ancestorDirObserver.observe(this, {
+      attributes: true,
+      attributeFilter: ['dir', 'lang'],
+    });
+
+    for (const ancestor of ancestorElements(this)) {
+      this.ancestorDirObserver.observe(ancestor, {
+        attributes: true,
+        attributeFilter: ['dir'],
+      });
+    }
+  }
+
+  override disconnectedCallback(): void {
+    this.ancestorDirObserver.disconnect();
+    super.disconnectedCallback();
   }
 
   private announceSelected(value: string): void {
@@ -90,10 +142,25 @@ export class BreadcrumbItem extends LikeAnchor(Focusable) {
   }
 
   protected renderLink(): TemplateResult {
+    // Forward `lang`/`dir` from the host onto the link so a single item's
+    // language only affects its own text rendering, not the host's own
+    // `direction` (which the separator mirrors via `:dir(rtl)`); see
+    // `:host { direction: inherit; }` in breadcrumb-item.css. Read the raw
+    // `dir` attribute rather than `this.dir` — `SpectrumElement` overrides
+    // the native `dir` getter to return the *computed* CSS direction, which
+    // is exactly what `direction: inherit` decouples from the attribute.
     return html`
       <a
         id="item-link"
         href=${ifDefined(!this.isLastOfType ? this.href : undefined)}
+        lang=${ifDefined(this.lang || undefined)}
+        dir=${ifDefined(
+          (this.getAttribute('dir') || undefined) as
+            | 'ltr'
+            | 'rtl'
+            | 'auto'
+            | undefined
+        )}
         tabindex="0"
         aria-current=${ifDefined(this.isLastOfType ? 'page' : undefined)}
         @keydown=${this.handleKeyDown}
@@ -105,11 +172,20 @@ export class BreadcrumbItem extends LikeAnchor(Focusable) {
   }
 
   private renderSeparator(): TemplateResult {
+    // `:dir()` resolves directionality by walking up the `dir` *attribute*
+    // chain, independent of the CSS `direction` property — so it still
+    // picks up this host's own `dir` (set for `#item-link`'s content, per
+    // `renderLink()`) even though `:host { direction: inherit; }` keeps the
+    // host's own *computed* direction tied to the ambient context. Read that
+    // computed value and set it explicitly here so `:dir()` on `#separator`
+    // resolves from its own accurate attribute instead of the host's.
+    const ambientDir = getComputedStyle(this).direction as 'ltr' | 'rtl';
     return html`
       <sp-icon-chevron100
         id="separator"
         size="xs"
         class="spectrum-UIIcon-ChevronRight100"
+        dir=${ambientDir}
       ></sp-icon-chevron100>
     `;
   }

1st-gen/packages/breadcrumbs/src/Breadcrumbs.ts

@@ -48,6 +48,8 @@ type BreadcrumbItem = {
   value: string;
   offsetWidth: number;
   isVisible: boolean; // false if displayed in menu overlay
+  lang?: string;
+  dir?: string;
 };
 
 /**
@@ -190,6 +192,11 @@ export class Breadcrumbs extends SpectrumElement {
         value: el.value || index.toString(),
         offsetWidth: width,
         isVisible: true,
+        lang: el.lang || undefined,
+        // `SpectrumElement` overrides `dir` to return the *computed* CSS
+        // direction rather than the attribute, so read the attribute
+        // directly to capture the item's own authored direction override.
+        dir: el.getAttribute('dir') || undefined,
       };
     });
   }
@@ -293,7 +300,12 @@ export class Breadcrumbs extends SpectrumElement {
 
           ${this.items.map(
             (item) => html`
-              <sp-menu-item href=${ifDefined(item.href)} value=${item.value}>
+              <sp-menu-item
+                href=${ifDefined(item.href)}
+                value=${item.value}
+                lang=${ifDefined(item.lang)}
+                dir=${ifDefined(item.dir as 'ltr' | 'rtl' | 'auto' | undefined)}
+              >
                 ${item.label}
               </sp-menu-item>
             `

1st-gen/packages/breadcrumbs/src/breadcrumb-item.css

@@ -19,3 +19,10 @@
 :host([disabled]) {
   pointer-events: none;
 }
+
+/* A `dir` set on this host (e.g. to localize one item's text) should not
+   flip this item's own layout or its separator's mirrored chevron; only
+   `#item-link` (see BreadcrumbItem.ts) picks up that direction. */
+:host {
+  direction: inherit;
+}

1st-gen/packages/breadcrumbs/stories/breadcrumbs.stories.ts

@@ -114,6 +114,43 @@ AddItemsDynamic.swc_vrt = {
   skip: true,
 };
 
+// Autonyms (each language's name rendered in that language), alphabetized
+// by the rendered text so both LTR and RTL scripts are interleaved.
+const languages = [
+  { value: 'de', label: 'Deutsch', lang: 'de', dir: 'ltr' },
+  { value: 'en', label: 'English', lang: 'en', dir: 'ltr' },
+  { value: 'es', label: 'Español', lang: 'es', dir: 'ltr' },
+  { value: 'fr', label: 'Français', lang: 'fr', dir: 'ltr' },
+  { value: 'ru', label: 'Русский', lang: 'ru', dir: 'ltr' },
+  { value: 'he', label: 'עברית', lang: 'he', dir: 'rtl' },
+  { value: 'ar', label: 'العربية', lang: 'ar', dir: 'rtl' },
+] as const;
+
+export const LanguageOfParts = (args: StoryArgs): TemplateResult => {
+  return html`
+    <sp-breadcrumbs
+      ${spreadProps(args)}
+      max-visible-items=${ifDefined(args['max-visible-items'])}
+      @change=${args.onChange}
+    >
+      ${languages.map(
+        (language) => html`
+          <sp-breadcrumb-item
+            value=${language.value}
+            lang=${language.lang}
+            dir=${language.dir}
+          >
+            ${language.label}
+          </sp-breadcrumb-item>
+        `
+      )}
+    </sp-breadcrumbs>
+  `;
+};
+LanguageOfParts.args = {
+  'max-visible-items': 3,
+};
+
 export const ShowRoot = (args: StoryArgs): TemplateResult => {
   return html`
     <sp-breadcrumbs

1st-gen/packages/breadcrumbs/test/breadcrumb-item.test.ts

@@ -103,4 +103,175 @@ describe('Breadcrumb Item', () => {
     expect(changeSpy.callCount).to.equal(1);
     expect(changeSpy).to.have.been.calledWith('home');
   });
+
+  it('scopes a per-item `dir` override to `#item-link`, not its own layout', async () => {
+    const el = await fixture<HTMLElement>(html`
+      <sp-breadcrumbs>
+        <sp-breadcrumb-item value="he" lang="he" dir="rtl">
+          עברית
+        </sp-breadcrumb-item>
+        <sp-breadcrumb-item value="en">English</sp-breadcrumb-item>
+      </sp-breadcrumbs>
+    `);
+
+    await elementUpdated(el);
+
+    const rtlItem = el.querySelector(
+      'sp-breadcrumb-item[value="he"]'
+    ) as BreadcrumbItem;
+    await elementUpdated(rtlItem);
+
+    // The host's own box keeps the ambient (LTR) direction, so its
+    // separator does not mirror out of step with its LTR siblings.
+    expect(getComputedStyle(rtlItem).direction, 'host direction').to.equal(
+      'ltr'
+    );
+
+    // Only the link carrying the item's text picks up the override.
+    const itemLink = rtlItem.shadowRoot.querySelector(
+      '#item-link'
+    ) as HTMLElement;
+    expect(itemLink.dir, 'item-link dir').to.equal('rtl');
+    expect(itemLink.lang, 'item-link lang').to.equal('he');
+    expect(
+      getComputedStyle(itemLink).direction,
+      'item-link direction'
+    ).to.equal('rtl');
+  });
+
+  it('mirrors the separator to match the ancestor dir, or the document default otherwise', async () => {
+    const el = await fixture<HTMLDivElement>(html`
+      <div>
+        <sp-breadcrumbs dir="rtl">
+          <sp-breadcrumb-item value="a">A</sp-breadcrumb-item>
+          <sp-breadcrumb-item value="b">B</sp-breadcrumb-item>
+        </sp-breadcrumbs>
+        <sp-breadcrumbs>
+          <sp-breadcrumb-item value="c">C</sp-breadcrumb-item>
+          <sp-breadcrumb-item value="d">D</sp-breadcrumb-item>
+        </sp-breadcrumbs>
+      </div>
+    `);
+
+    await elementUpdated(el);
+
+    const rtlItem = el.querySelector(
+      'sp-breadcrumbs[dir="rtl"] sp-breadcrumb-item[value="a"]'
+    ) as BreadcrumbItem;
+    await elementUpdated(rtlItem);
+
+    const rtlSeparator = rtlItem.shadowRoot.querySelector(
+      '#separator'
+    ) as HTMLElement;
+    expect(
+      getComputedStyle(rtlSeparator).transform,
+      'separator mirrors under a dir="rtl" ancestor'
+    ).to.not.equal('none');
+
+    const defaultItem = el.querySelector(
+      'sp-breadcrumbs:not([dir]) sp-breadcrumb-item[value="c"]'
+    ) as BreadcrumbItem;
+    await elementUpdated(defaultItem);
+
+    const defaultSeparator = defaultItem.shadowRoot.querySelector(
+      '#separator'
+    ) as HTMLElement;
+    expect(
+      getComputedStyle(defaultSeparator).transform,
+      'separator matches the document default (ltr) absent an ancestor dir'
+    ).to.equal('none');
+  });
+
+  it('does not mirror the separator for a single item whose own dir mismatches the ambient direction', async () => {
+    const el = await fixture<HTMLElement>(html`
+      <sp-breadcrumbs>
+        <sp-breadcrumb-item value="he" lang="he" dir="rtl">
+          עברית
+        </sp-breadcrumb-item>
+        <sp-breadcrumb-item value="en">English</sp-breadcrumb-item>
+      </sp-breadcrumbs>
+    `);
+
+    await elementUpdated(el);
+
+    const mismatchedItem = el.querySelector(
+      'sp-breadcrumb-item[value="he"]'
+    ) as BreadcrumbItem;
+    await elementUpdated(mismatchedItem);
+
+    // `:dir()` resolves via the attribute chain, so absent the explicit
+    // `dir` set on `#separator` in `renderSeparator()` it would incorrectly
+    // pick up this host's own `dir="rtl"` (meant only for `#item-link`).
+    const separator = mismatchedItem.shadowRoot.querySelector(
+      '#separator'
+    ) as HTMLElement;
+    expect(separator.getAttribute('dir'), 'separator dir attribute').to.equal(
+      'ltr'
+    );
+    expect(
+      getComputedStyle(separator).transform,
+      'separator stays unmirrored, matching its ltr siblings'
+    ).to.equal('none');
+  });
+
+  it('updates the separator when an ancestor dir changes after the item has mounted', async () => {
+    const el = await fixture<HTMLElement>(html`
+      <sp-breadcrumbs>
+        <sp-breadcrumb-item value="a">A</sp-breadcrumb-item>
+        <sp-breadcrumb-item value="b">B</sp-breadcrumb-item>
+      </sp-breadcrumbs>
+    `);
+
+    await elementUpdated(el);
+
+    const item = el.querySelector(
+      'sp-breadcrumb-item[value="a"]'
+    ) as BreadcrumbItem;
+    await elementUpdated(item);
+
+    const separator = item.shadowRoot.querySelector(
+      '#separator'
+    ) as HTMLElement;
+    expect(
+      getComputedStyle(separator).transform,
+      'unmirrored before the ancestor sets dir="rtl"'
+    ).to.equal('none');
+
+    el.setAttribute('dir', 'rtl');
+    await elementUpdated(item);
+    // The ancestor MutationObserver triggers `requestUpdate()`, which is
+    // async relative to the attribute mutation itself.
+    await item.updateComplete;
+
+    expect(
+      getComputedStyle(separator).transform,
+      'mirrored once the ancestor dir changes after mount'
+    ).to.not.equal('none');
+  });
+
+  it("updates #item-link when this item's own lang/dir change after mount", async () => {
+    const el = await fixture<BreadcrumbItem>(html`
+      <sp-breadcrumb-item value="home">Home</sp-breadcrumb-item>
+    `);
+
+    await elementUpdated(el);
+
+    const itemLink = el.shadowRoot.querySelector('#item-link') as HTMLElement;
+    expect(itemLink.lang, 'no lang before it is set').to.equal('');
+    expect(itemLink.dir, 'no dir before it is set').to.equal('');
+
+    el.setAttribute('lang', 'he');
+    el.setAttribute('dir', 'rtl');
+    await el.updateComplete;
+
+    expect(itemLink.lang, 'lang updates after mount').to.equal('he');
+    expect(itemLink.dir, 'dir updates after mount').to.equal('rtl');
+
+    el.removeAttribute('lang');
+    el.removeAttribute('dir');
+    await el.updateComplete;
+
+    expect(itemLink.lang, 'lang clears after being removed').to.equal('');
+    expect(itemLink.dir, 'dir clears after being removed').to.equal('');
+  });
 });