@astryxdesign/core 0.4.4 → 0.4.5-canary.0472ec1

package/src/Markdown/Markdown.tsx

@@ -53,6 +53,9 @@ import {
   parseMarkdownIncremental,
   createIncrementalState,
   trimStreamingArtifacts,
+  inlineText,
+  slugify,
+  uniqueSlug,
 } from './parser';
 import type {BlockNode, InlineNode, IncrementalState} from './parser';
 import {themeProps} from '../utils/themeProps';
@@ -108,6 +111,14 @@ export interface MarkdownComponents {
   heading?: React.ComponentType<{
     level: 1 | 2 | 3 | 4 | 5 | 6;
     children: React.ReactNode;
+    /**
+     * Generated slug for this heading, matching the ids produced by
+     * useOutlineFromMarkdown / parseOutlineFromMarkdown. Render it as the
+     * element's `id` to keep Outline hash navigation working. Undefined for
+     * headings nested inside blockquotes or list items (the outline only
+     * lists top-level headings).
+     */
+    id?: string;
   }>;
   paragraph?: React.ComponentType<{children: React.ReactNode}>;
   image?: React.ComponentType<{src: string; alt: string}>;
@@ -1045,6 +1056,7 @@ function renderBlock(
   inlinePlugins: MarkdownInlinePlugin[] | undefined,
   components: Partial<MarkdownComponents> | undefined,
   t: TranslatorFn,
+  headingIdMap?: ReadonlyMap<BlockNode, string>,
 ): SyncReactNode {
   const blockAlignMargin = BLOCK_ALIGN_MARGIN[contentAlign];
   const blockAlignStyle =
@@ -1071,10 +1083,15 @@ function renderBlock(
           components,
         ),
       );
+      // Only top-level headings get an id: the map is built from the same
+      // traversal parseOutlineFromMarkdown uses (which skips headings nested
+      // in blockquotes / list items), so rendered ids and outline ids stay
+      // identical — including duplicate-slug numbering.
+      const headingId = headingIdMap?.get(node);
       const HeadingComp = components?.heading;
       if (HeadingComp) {
         return (
-          <HeadingComp key={index} level={level}>
+          <HeadingComp key={index} level={level} id={headingId}>
             {headingChildren}
           </HeadingComp>
         );
@@ -1083,6 +1100,7 @@ function renderBlock(
       return (
         <Tag
           key={index}
+          id={headingId}
           {...mergeProps(
             themeProps('markdown-heading', {density, level}),
             stylex.props(
@@ -1652,6 +1670,27 @@ export function Markdown({
     return parseMarkdown(children, parseOptions);
   }, [display, smoothedText, children, isStreaming, parseOptions]);
 
+  // Assign each top-level heading the slug that parseOutlineFromMarkdown
+  // would derive for it, so Outline hash links built from the same source
+  // always find a matching DOM id. Mirrors that function's traversal exactly:
+  // top-level blocks only, one shared duplicate-numbering sequence.
+  // NOTE: must stay above the `display === 'inline'` early return below —
+  // hooks cannot be conditional.
+  const headingIdMap = useMemo(() => {
+    if (display === 'inline' || blocks.length === 0) {
+      return undefined;
+    }
+    const map = new Map<BlockNode, string>();
+    const counts = new Map<string, number>();
+    for (const block of blocks) {
+      if (block.type === 'heading') {
+        const label = inlineText(block.children).trim();
+        map.set(block, uniqueSlug(slugify(label), counts));
+      }
+    }
+    return map;
+  }, [display, blocks]);
+
   const inlineNodes = useMemo(() => {
     if (display !== 'inline') {
       return [];
@@ -1765,6 +1804,7 @@ export function Markdown({
           inlinePlugins,
           components,
           t,
+          headingIdMap,
         ),
       )}
     </div>

package/src/Markdown/parser.ts

@@ -3,8 +3,10 @@
 /**
  * @file parser.ts
  * @input Markdown string
- * @output Array of MarkdownNode AST nodes
- * @position Core parser; consumed by Markdown.tsx
+ * @output Array of MarkdownNode AST nodes; heading slug helpers
+ *   (inlineText, slugify, uniqueSlug) shared by Markdown rendering and
+ *   Outline's parseOutlineFromMarkdown
+ * @position Core parser; consumed by Markdown.tsx and Outline
  */
 
 // ---------------------------------------------------------------------------
@@ -1815,3 +1817,59 @@ export function parseMarkdownIncremental(
 
   return mergeSettledBlocks(settledBlocks, unsettledBlocks);
 }
+
+// ---------------------------------------------------------------------------
+// Heading slugs
+// ---------------------------------------------------------------------------
+// Single source of truth for the heading id contract: Markdown renders these
+// slugs as `id` attributes on h1–h6, and Outline's parseOutlineFromMarkdown
+// derives its item ids from the same functions, so outline hash links always
+// resolve to a rendered heading by construction.
+
+/** Flatten inline nodes into their plain text content. */
+export function inlineText(nodes: InlineNode[]): string {
+  return nodes
+    .map(node => {
+      switch (node.type) {
+        case 'text':
+        case 'code':
+          return node.content;
+        case 'bold':
+        case 'italic':
+        case 'strikethrough':
+        case 'link':
+          return inlineText(node.children);
+        case 'image':
+          return node.alt;
+        case 'citation':
+        case 'break':
+          return '';
+      }
+    })
+    .join('');
+}
+
+/** Turn heading text into a URL-safe slug (lowercase, hyphen-separated). */
+export function slugify(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/['"]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Disambiguate repeated slugs with a numeric suffix (`setup`, `setup-1`, …).
+ * Empty slugs fall back to `section`. The caller owns the counts map so one
+ * document shares a single numbering sequence.
+ */
+export function uniqueSlug(
+  baseSlug: string,
+  counts: Map<string, number>,
+): string {
+  const fallbackSlug = baseSlug || 'section';
+  const count = counts.get(fallbackSlug) ?? 0;
+  counts.set(fallbackSlug, count + 1);
+  return count === 0 ? fallbackSlug : `${fallbackSlug}-${count}`;
+}

package/src/MobileNav/MobileNav.tsx

@@ -23,6 +23,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/MobileNav/index.ts (exports if types change)
+ * - /packages/core/src/hooks/scrollbarGutter.ts (shared scroll-lock gutter)
  * - /packages/cli/assets/templates/blocks/components/MobileNav/ (showcase blocks)
  */
 
@@ -47,7 +48,12 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {Heading} from '../Heading/Heading';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
+import {
+  holdScrollbarGutter,
+  type ScrollbarGutterHold,
+} from '../hooks/scrollbarGutter';
 import {mergeProps, mergeRefs, composeEventHandlers} from '../utils';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -70,7 +76,16 @@ const styles = stylex.create({
     width: '100vw',
     height: '100dvh',
     backgroundColor: 'transparent',
-    overflow: 'hidden',
+    // `clip`, not `hidden`. Both clip the off-screen drawer, but `hidden` makes
+    // the dialog a SCROLL CONTAINER, and a scroll container in the top layer
+    // whose subtree holds another scroller (the drawer's content area) does not
+    // paint a @starting-style entry transition for its descendants in Chromium:
+    // the transition ticks in the CSSOM while every painted frame shows the
+    // end value, so the drawer appears fully open. `clip` clips without
+    // creating a scroll container and the slide-in paints normally. The dialog
+    // never scrolls anyway — its child is absolutely positioned — so nothing
+    // depended on it being a scroll container.
+    overflow: 'clip',
     overscrollBehavior: 'contain',
     // Prevent touch gestures (pull-to-refresh, background scroll) passing through
     touchAction: 'none',
@@ -112,7 +127,14 @@ const styles = stylex.create({
   },
   backdropOpen: {
     '::backdrop': {
-      opacity: 1,
+      // The ::backdrop only exists once showModal() has put the dialog in the
+      // top layer, so its first rendered frame already has the open opacity.
+      // Without a starting style there is no earlier value to transition from
+      // and the scrim snaps in — @starting-style supplies that value.
+      opacity: {
+        default: 1,
+        '@starting-style': 0,
+      },
     },
   },
   drawer: {
@@ -143,7 +165,17 @@ const styles = stylex.create({
     },
   },
   drawerStartOpen: {
-    transform: 'translateX(0)',
+    // The whole dialog is `display: none` while closed, so the drawer is not
+    // rendered and the open transform is the only value it has ever had — a
+    // transition needs a previous value to run from. @starting-style gives the
+    // first rendered frame the off-screen transform, so the slide-in plays.
+    transform: {
+      default: 'translateX(0)',
+      '@starting-style': {
+        default: 'translateX(-100%)',
+        ':is([dir="rtl"] *)': 'translateX(100%)',
+      },
+    },
   },
   drawerEnd: {
     insetInlineEnd: 0,
@@ -156,7 +188,14 @@ const styles = stylex.create({
     },
   },
   drawerEndOpen: {
-    transform: 'translateX(0)',
+    // See drawerStartOpen — same starting style, mirrored edge.
+    transform: {
+      default: 'translateX(0)',
+      '@starting-style': {
+        default: 'translateX(100%)',
+        ':is([dir="rtl"] *)': 'translateX(-100%)',
+      },
+    },
   },
   header: {
     display: 'flex',
@@ -396,6 +435,15 @@ export function MobileNav({
 
   const dialogRef = useRef<HTMLDialogElement>(null);
   const closeTimeoutRef = useRef<ReturnType<typeof setTimeout>>(null);
+  const gutterRef = useRef<ScrollbarGutterHold | null>(null);
+
+  // Gives back the gutter held open in place of the hidden scrollbar.
+  const releaseGutter = useCallback(() => {
+    if (gutterRef.current) {
+      gutterRef.current.release();
+      gutterRef.current = null;
+    }
+  }, []);
   // Resolved side — computed from trigger position when side='auto'
   const [resolvedSide, setResolvedSide] = useState<'start' | 'end'>(
     side === 'auto' ? 'end' : side,
@@ -438,6 +486,10 @@ export function MobileNav({
     }
 
     if (isOpen) {
+      // Taken first: every mutation below is one that can hide the scrollbar,
+      // and the gutter has to be measured while it is still there.
+      gutterRef.current ??= holdScrollbarGutter(document.documentElement);
+
       if (!dialog.open) {
         dialog.showModal();
       }
@@ -445,8 +497,10 @@ export function MobileNav({
       // overflow: clip avoids creating a scroll container (unlike hidden),
       // so there's no scroll bounce and no need to save/restore scroll position.
       document.documentElement.style.overflow = 'clip';
+      gutterRef.current.settle();
     } else if (dialog.open) {
       document.documentElement.style.overflow = '';
+      releaseGutter();
 
       closeTimeoutRef.current = setTimeout(() => {
         dialog.close();
@@ -459,8 +513,9 @@ export function MobileNav({
         closeTimeoutRef.current = null;
       }
       document.documentElement.style.overflow = '';
+      releaseGutter();
     };
-  }, [isOpen]);
+  }, [isOpen, releaseGutter]);
 
   // Close the native dialog on unmount if it's still open. Inside AppShell the
   // drawer is mounted in an <Activity> that switches to mode="hidden" when the
@@ -512,6 +567,7 @@ export function MobileNav({
         themeProps('mobile-nav', {side: resolvedSide}),
         stylex.props(
           styles.dialog,
+          overlayPaddingReset.reset,
           isOpen && styles.open,
           styles.backdrop,
           isOpen && styles.backdropOpen,

package/src/MobileNav/MobileNavEntryAnimation.test.tsx

@@ -0,0 +1,212 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MobileNavEntryAnimation.test.tsx
+ * @input Uses vitest, @testing-library/react, the TypeScript compiler API
+ * @output Regression tests keeping the drawer's slide-in and scrim fade-in
+ * @position Testing; guards the open path of MobileNav.tsx
+ *
+ * The drawer used to open with no animation at all while closing smoothly.
+ *
+ * The dialog is `display: none` until `isOpen`, so nothing inside it is
+ * rendered while closed. React commits the open `display` and the open
+ * `transform` in the same pass, which means the first frame the drawer is ever
+ * rendered in already holds the open transform: a transition has no earlier
+ * value to run from and the drawer simply appears. Closing looked fine because
+ * both values exist by then — `display` stays in the transition with
+ * `allow-discrete`, so the element is still rendered as the transform animates
+ * out.
+ *
+ * `@starting-style` supplies that before-change style — the off-screen
+ * transform for the drawer, transparent for the `::backdrop`.
+ *
+ * That alone is NOT enough, and the second half is the part that is easy to
+ * undo by accident. The dialog used `overflow: hidden`, which makes it a
+ * SCROLL CONTAINER. A scroll container in the top layer whose subtree holds
+ * another scroller — here the drawer's own content area — does not paint a
+ * `@starting-style` entry transition for its descendants in Chromium: the
+ * transition ticks in the CSSOM (`getComputedStyle` interpolates perfectly)
+ * while every painted frame shows the end value. Measuring the CSSOM says
+ * "animating"; the screen says "snapped". `overflow: clip` clips the
+ * off-screen drawer exactly as `hidden` did without creating a scroll
+ * container, and the slide-in paints.
+ *
+ * Reproduced minimally: dialog `overflow: hidden` + a scrolling child inside
+ * the drawer snaps; either one alone animates.
+ *
+ * Note on scope: jsdom has no top layer, no transitions, no `@starting-style`
+ * evaluation and no compositor, so none of this is observable here. These
+ * tests pin the three declarations the behaviour rests on. Verified in
+ * Chromium by screencasting painted frames (not computed style) at both edges,
+ * LTR and RTL: open and close each paint ~60-100 distinct intermediate
+ * positions, and reduced motion collapses to a 10ms transition.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import ts from 'typescript';
+import {MobileNav} from './MobileNav';
+
+// jsdom doesn't implement showModal/close on <dialog>, so we mock them
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal =
+    HTMLDialogElement.prototype.showModal ||
+    function (this: HTMLDialogElement) {
+      this.setAttribute('open', '');
+    };
+  HTMLDialogElement.prototype.close =
+    HTMLDialogElement.prototype.close ||
+    function (this: HTMLDialogElement) {
+      this.removeAttribute('open');
+    };
+});
+
+/** Every CSS rule StyleX has injected into the document, as text. */
+function injectedRules(): string[] {
+  const rules: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let cssRules: CSSRuleList;
+    try {
+      cssRules = sheet.cssRules;
+    } catch {
+      continue;
+    }
+    for (const rule of Array.from(cssRules)) {
+      rules.push(rule.cssText);
+    }
+  }
+  return rules;
+}
+
+describe('MobileNav scrim fades in', () => {
+  it('gives the ::backdrop a transparent starting style', () => {
+    render(
+      <MobileNav isOpen onOpenChange={() => {}} data-testid="mobile-nav">
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    const classes = Array.from(screen.getByTestId('mobile-nav').classList);
+    // Without this the scrim is opaque in the frame the dialog enters the top
+    // layer, so it has nothing to fade from and snaps in behind the drawer.
+    const startingStyleForThisDialog = injectedRules().filter(
+      rule =>
+        rule.startsWith('@starting-style') &&
+        rule.includes('::backdrop') &&
+        classes.some(cls => rule.includes(`.${cls}`)),
+    );
+
+    expect(startingStyleForThisDialog).toHaveLength(1);
+    expect(startingStyleForThisDialog[0]).toMatch(/opacity:\s*0/);
+  });
+});
+
+// =============================================================================
+// Drawer slide-in — asserted on the style definition
+// =============================================================================
+
+const SOURCE = readFileSync(join(__dirname, 'MobileNav.tsx'), 'utf8');
+
+/**
+ * The object literal a `styles.<name>` key is defined with, e.g. the value of
+ * `drawerStartOpen` inside the file's `stylex.create({...})` call.
+ */
+function styleDefinition(name: string): ts.ObjectLiteralExpression {
+  const file = ts.createSourceFile(
+    'MobileNav.tsx',
+    SOURCE,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+
+  let found: ts.ObjectLiteralExpression | undefined;
+  const visit = (node: ts.Node) => {
+    if (
+      ts.isPropertyAssignment(node) &&
+      ts.isIdentifier(node.name) &&
+      node.name.text === name &&
+      ts.isObjectLiteralExpression(node.initializer)
+    ) {
+      found = node.initializer;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+
+  if (!found) {
+    throw new Error(`No style named "${name}" in MobileNav.tsx`);
+  }
+  return found;
+}
+
+/** The value of one property of a style definition, as source text. */
+function property(style: ts.ObjectLiteralExpression, key: string): string {
+  const prop = style.properties.find(
+    p =>
+      ts.isPropertyAssignment(p) &&
+      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+      p.name.text === key,
+  );
+
+  if (!prop) {
+    throw new Error(`No "${key}" in ${style.getText().slice(0, 40)}…`);
+  }
+  return (prop as ts.PropertyAssignment).initializer.getText();
+}
+
+describe('MobileNav dialog does not become a scroll container', () => {
+  it('clips the off-screen drawer with `clip`, not `hidden`', () => {
+    // This is the half of the fix with no visible declaration of its own
+    // purpose: `hidden` looks like a pure clipping choice and clips exactly as
+    // well, so it is an easy "harmless tidy-up" to make. It is not harmless —
+    // it makes the dialog a scroll container, and the entry animation then
+    // ticks in the CSSOM without ever painting. See the file header.
+    expect(property(styleDefinition('dialog'), 'overflow')).toBe("'clip'");
+  });
+});
+
+describe.each([
+  {
+    name: 'drawerStartOpen',
+    offscreen: 'translateX(-100%)',
+    offscreenRtl: 'translateX(100%)',
+  },
+  {
+    name: 'drawerEndOpen',
+    offscreen: 'translateX(100%)',
+    offscreenRtl: 'translateX(-100%)',
+  },
+])('MobileNav drawer slides in ($name)', ({name, offscreen, offscreenRtl}) => {
+  it('opens to the on-screen transform', () => {
+    expect(property(styleDefinition(name), 'transform')).toContain(
+      'translateX(0)',
+    );
+  });
+
+  it('starts off-screen so the open transform has something to run from', () => {
+    const transform = property(styleDefinition(name), 'transform');
+
+    // The whole point: the first rendered frame needs the closed transform.
+    // Drop this and the drawer is simply there, fully open, on frame one —
+    // while the close still animates, which is what made the bug look like a
+    // missing entry animation rather than a missing starting style.
+    expect(transform).toContain('@starting-style');
+    expect(transform).toContain(offscreen);
+    // Mirrored, like the closed styles it has to match: sliding in from the
+    // wrong edge in RTL is as broken as not sliding at all.
+    expect(transform).toContain(offscreenRtl);
+  });
+
+  it('starts from the same edge the closed style parks it at', () => {
+    const closed = property(
+      styleDefinition(name.replace('Open', '')),
+      'transform',
+    );
+
+    expect(closed).toContain(offscreen);
+    expect(closed).toContain(offscreenRtl);
+  });
+});

package/src/MobileNav/MobileNavScrollbarGutter.test.tsx

@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MobileNavScrollbarGutter.test.tsx
+ * @input Uses vitest, @testing-library/react, MobileNav, a stubbed viewport
+ * @output Unit tests for the scrollbar gutter MobileNav reserves while open
+ * @position Testing; guards MobileNav.tsx against the open-drawer page shift
+ *
+ * MobileNav clips the document to lock background scroll, which hides a
+ * classic scrollbar and widens the layout viewport by its width — the page
+ * behind the drawer jumps sideways. The clip has to be paired with holding
+ * that gutter open.
+ *
+ * SYNC: When MobileNav.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, beforeAll, afterEach} from 'vitest';
+import {render, cleanup} from '@testing-library/react';
+import {MobileNav} from './MobileNav';
+
+beforeAll(() => {
+  // jsdom doesn't implement showModal/close on <dialog>
+  HTMLDialogElement.prototype.showModal =
+    HTMLDialogElement.prototype.showModal ||
+    function (this: HTMLDialogElement) {
+      this.setAttribute('open', '');
+    };
+  HTMLDialogElement.prototype.close =
+    HTMLDialogElement.prototype.close ||
+    function (this: HTMLDialogElement) {
+      this.removeAttribute('open');
+    };
+});
+
+/** jsdom does no layout, so both halves of the measurement are stubbed. */
+function stubViewport(innerWidth: number, clientWidth: number) {
+  Object.defineProperty(window, 'innerWidth', {
+    value: innerWidth,
+    configurable: true,
+    writable: true,
+  });
+  Object.defineProperty(document.documentElement, 'clientWidth', {
+    value: clientWidth,
+    configurable: true,
+  });
+}
+
+const rootGutter = () => document.documentElement.style.scrollbarGutter;
+
+describe('MobileNav scrollbar gutter', () => {
+  afterEach(() => {
+    cleanup();
+    document.documentElement.style.cssText = '';
+    // @ts-expect-error -- drop the viewport stub so jsdom's own value comes back
+    delete document.documentElement.clientWidth;
+  });
+
+  it('holds the gutter open while the drawer is open', () => {
+    stubViewport(1024, 1009);
+
+    const view = render(
+      <MobileNav isOpen={true} onOpenChange={() => {}}>
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    expect(document.documentElement.style.overflow).toBe('clip');
+    expect(rootGutter()).toBe('stable');
+
+    view.unmount();
+
+    expect(document.documentElement.style.overflow).toBe('');
+    expect(rootGutter()).toBe('');
+  });
+
+  it('gives the gutter back when the drawer closes', () => {
+    stubViewport(1024, 1009);
+
+    const view = render(
+      <MobileNav isOpen={true} onOpenChange={() => {}}>
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    expect(rootGutter()).toBe('stable');
+
+    view.rerender(
+      <MobileNav isOpen={false} onOpenChange={() => {}}>
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    expect(rootGutter()).toBe('');
+  });
+
+  it('holds nothing when the scrollbar is an overlay one', () => {
+    stubViewport(1024, 1024);
+
+    render(
+      <MobileNav isOpen={true} onOpenChange={() => {}}>
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    expect(document.documentElement.style.overflow).toBe('clip');
+    expect(rootGutter()).toBe('');
+    expect(document.documentElement.style.paddingRight).toBe('');
+  });
+});

package/src/MultiSelector/MultiSelector.test.tsx

@@ -1790,7 +1790,7 @@ describe('MultiSelector clear icon theme target', () => {
     expect(css).toContain('.astryx-multi-selector-clear-icon {');
     expect(css).toContain('width: 12px');
     expect(css).toContain('height: 12px');
-    expect(css).toContain('.astryx-multi-selector-clear-icon:hover {');
+    expect(css).toContain('.astryx-multi-selector-clear-icon:hover');
     expect(css).toContain('color: var(--color-icon-primary)');
   });
 });

package/src/MultiSelector/MultiSelector.tsx

@@ -73,6 +73,7 @@ import {
 import {useMultiCombobox} from './hooks';
 import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {useSize} from '../SizeContext/SizeContext';
@@ -189,16 +190,17 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     backgroundImage: {
       default: null,
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`,
       },
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
     boxShadow: {
       default: 'none',
-      ':hover:not(:focus-within)': {
-        '@media (hover: hover)': 'none',
-      },
+      ':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
+        {
+          '@media (hover: hover)': 'none',
+        },
       ':focus-within': 'none',
     },
     fontWeight: fontWeightVars['--font-weight-medium'],
@@ -706,6 +708,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   style,
 }: MultiSelectorProps<T>) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder =
     placeholderFromProps ?? t('@astryx.multiSelector.selectPlaceholder');
   const selectAllLabel =
@@ -1526,7 +1529,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           }
           aria-describedby={ariaDescribedBy}
           aria-labelledby={ariaLabelledBy}
-          aria-required={isRequired ? 'true' : undefined}
+          aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={status?.type === 'error' ? 'true' : undefined}
           aria-busy={isBusy || undefined}
           // With a disabledMessage the trigger keeps focusability via