@astryxdesign/core 0.3.0 → 0.4.0-canary.058f476

package/src/Layer/useLayer.tsx

@@ -50,6 +50,18 @@ const styles = stylex.create({
   fixed: {
     position: 'fixed',
   },
+  // Clearance from the anchor. Set on BOTH edges of the placement axis, not
+  // just the one facing the anchor: `position-try-fallbacks` can flip the
+  // layer to the opposite side at paint time, and a single-edge margin then
+  // lands on the far side and the gap vanishes (#4803).
+  offsetBlock: (offset: string) => ({
+    marginBlockStart: offset,
+    marginBlockEnd: offset,
+  }),
+  offsetInline: (offset: string) => ({
+    marginInlineStart: offset,
+    marginInlineEnd: offset,
+  }),
 });
 
 /**
@@ -94,6 +106,20 @@ export interface ContextRenderProps {
    * is `'custom'`.
    */
   alignment?: LayerAlignment;
+  /**
+   * Clearance between the layer and its anchor, as a CSS length (a number is
+   * treated as `px`). Applied along the placement axis and flip-safe, so the
+   * gap survives a `position-try-fallbacks` flip to the opposite side.
+   *
+   * Layers sit flush by default: the hook zeroes the UA margins so anchor
+   * positioning has a clean box, and clearance is a deliberate choice per
+   * surface. `var(--spacing-1)` is the system's standard clearance.
+   *
+   * Ignored when `positioning` is `'custom'` — that mode owns its own insets.
+   *
+   * @default 0
+   */
+  offset?: number | string;
   /**
    * ARIA role applied to the popover container (e.g. `'tooltip'`). Lets
    * consumers complete the ARIA pattern and gives test tooling a stable,
@@ -284,6 +310,10 @@ export interface FixedLayerReturn {
   render: (children: ReactNode, props: FixedRenderProps) => ReactNode;
 }
 
+function toCssLength(value: number | string): string {
+  return typeof value === 'number' ? `${value}px` : value;
+}
+
 /**
  * Map logical placement/alignment to a CSS position-area value.
  *
@@ -530,6 +560,7 @@ export function useLayer(
         placement = 'above',
         alignment = 'center',
         positioning = 'anchor',
+        offset,
         role,
         'aria-label': ariaLabel,
         xstyle,
@@ -555,7 +586,14 @@ export function useLayer(
               ),
             };
 
-      const stylexResult = stylex.props(styles.base, xstyle);
+      const offsetStyle =
+        positioning === 'anchor' && offset
+          ? placement === 'above' || placement === 'below'
+            ? styles.offsetBlock(toCssLength(offset))
+            : styles.offsetInline(toCssLength(offset))
+          : null;
+
+      const stylexResult = stylex.props(styles.base, offsetStyle, xstyle);
       const combinedClassName = extraClassName
         ? `${extraClassName} ${stylexResult.className ?? ''}`
         : stylexResult.className;

package/src/Lightbox/Lightbox.doc.mjs

@@ -77,7 +77,7 @@ export const docs = {
     defaults: {
       isOpen: false,
       media: {
-        src: 'https://lookaside.facebook.com/assets/astryx/light-scene-horizontal-1.png',
+        src: '/template-assets/light-scene-horizontal-1.png',
         alt: 'Coastal shoreline with ocean waves',
         caption: 'A scenic coastline with waves rolling onto a sandy beach beneath a clear sky.',
       },

package/src/Lightbox/Lightbox.tsx

@@ -35,6 +35,7 @@ import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 
 /**
@@ -158,16 +159,6 @@ const styles = stylex.create({
       '@media (hover: hover)': 'zoom-in',
     },
   },
-  zoomTarget: {
-    outline: {
-      default: 'none',
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
-  },
   imageWrapperZoomed: {
     cursor: 'grab',
   },
@@ -215,7 +206,12 @@ const styles = stylex.create({
   navButton: {
     position: 'absolute',
     top: '50%',
-    transform: 'translateY(-50%)',
+    // The individual `translate` property, not `transform`: this style now
+    // lands on the Button root, and a `transform` here replaces the Button's
+    // own transform rules — measured: the `scale(0.98)` press feedback stops
+    // firing. `translate` composes with them, reproducing exactly what the
+    // removed wrapper element did (wrapper translated, button scaled).
+    translate: '0 -50%',
     zIndex: 1,
   },
   navPrev: {
@@ -595,34 +591,33 @@ export function Lightbox({
       {...props}>
       <div ref={containerRef} {...stylex.props(styles.container)}>
         {/* Close button */}
-        <div {...stylex.props(styles.closeButton)}>
-          <IconButton
-            icon={<Icon icon="close" size="sm" color="inherit" />}
-            label={t('@astryx.lightbox.close')}
-            variant="ghost"
-            onClick={handleClose}
-            xstyle={styles.controlButton}
-          />
-        </div>
+        <IconButton
+          icon={<Icon icon="close" size="sm" color="inherit" />}
+          label={t('@astryx.lightbox.close')}
+          variant="ghost"
+          onClick={handleClose}
+          xstyle={[styles.closeButton, styles.controlButton]}
+        />
 
         {/* Gallery nav: prev — stays mounted and is disabled at the start of
             the range so pressing/arrowing to the boundary doesn't unmount the
             focused control and drop focus to <body>. */}
         {isGallery && (
-          <div {...stylex.props(styles.navButton, styles.navPrev)}>
-            <IconButton
-              icon={
-                <span {...stylex.props(rtlStyles.mirror)}>
-                  <Icon icon="chevronLeft" size="sm" color="inherit" />
-                </span>
-              }
-              label={t('@astryx.lightbox.previous')}
-              variant="ghost"
-              isDisabled={!canPrev}
-              onClick={goToPrev}
-              xstyle={styles.controlButton}
-            />
-          </div>
+          <IconButton
+            icon={
+              <Icon
+                icon="chevronLeft"
+                size="sm"
+                color="inherit"
+                xstyle={rtlStyles.mirror}
+              />
+            }
+            label={t('@astryx.lightbox.previous')}
+            variant="ghost"
+            isDisabled={!canPrev}
+            onClick={goToPrev}
+            xstyle={[styles.navButton, styles.navPrev, styles.controlButton]}
+          />
         )}
 
         {/* Media + caption group (centered together) */}
@@ -637,7 +632,7 @@ export function Lightbox({
             aria-label={isZoomTarget ? t('@astryx.lightbox.zoom') : undefined}
             {...stylex.props(
               styles.imageWrapper,
-              isZoomTarget && styles.zoomTarget,
+              isZoomTarget && focusOutlineStyles.focusVisible,
               !isVideo && hasZoom && !isZoomed && styles.imageWrapperZoomable,
               !isVideo && isZoomed && styles.imageWrapperZoomed,
               !isVideo && isDragging && styles.imageWrapperDragging,
@@ -676,20 +671,21 @@ export function Lightbox({
         {/* Gallery nav: next — see "prev" above; stays mounted and disabled at
             the end of the range instead of unmounting. */}
         {isGallery && (
-          <div {...stylex.props(styles.navButton, styles.navNext)}>
-            <IconButton
-              icon={
-                <span {...stylex.props(rtlStyles.mirror)}>
-                  <Icon icon="chevronRight" size="sm" color="inherit" />
-                </span>
-              }
-              label={t('@astryx.lightbox.next')}
-              variant="ghost"
-              isDisabled={!canNext}
-              onClick={goToNext}
-              xstyle={styles.controlButton}
-            />
-          </div>
+          <IconButton
+            icon={
+              <Icon
+                icon="chevronRight"
+                size="sm"
+                color="inherit"
+                xstyle={rtlStyles.mirror}
+              />
+            }
+            label={t('@astryx.lightbox.next')}
+            variant="ghost"
+            isDisabled={!canNext}
+            onClick={goToNext}
+            xstyle={[styles.navButton, styles.navNext, styles.controlButton]}
+          />
         )}
 
         {/* Gallery counter */}

package/src/Link/Link.tsx

@@ -44,6 +44,7 @@ import {mergeProps} from '../utils';
 import {computeTargetAndRel} from './computeTargetAndRel';
 import {useInteractiveRole} from '../hooks/useInteractiveRole';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTranslator} from '../i18n';
 
 /**
@@ -68,14 +69,6 @@ const styles = stylex.create({
     transitionProperty: 'color, text-decoration',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
   /**
    * Reset styles for rendering as a <button> when href is undefined.
@@ -368,7 +361,7 @@ export function Link({
         disabled={isDisabled}
         {...mergeProps(
           themeProps('link', {color}),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             styles.base,
             styles.buttonReset,
             linkColorStyles[color],
@@ -400,7 +393,7 @@ export function Link({
         tabIndex={-1}
         {...mergeProps(
           themeProps('link', {color}),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             styles.base,
             linkColorStyles[color],
             hasUnderline && styles.hasUnderline,
@@ -428,7 +421,7 @@ export function Link({
         tabIndex={isDisabled ? -1 : undefined}
         {...mergeProps(
           themeProps('link', {color}),
-          stylex.props(
+          focusOutlineProps.focusVisible(
             styles.base,
             linkColorStyles[color],
             hasUnderline && styles.hasUnderline,

package/src/MobileNav/MobileNav.tsx

@@ -453,9 +453,9 @@ export function MobileNav({
         {/* Header — content + close button */}
         <div {...stylex.props(styles.header, !header && styles.headerNoTitle)}>
           {typeof header === 'string' ? (
-            <span {...stylex.props(styles.headerText)}>
-              <Heading level={2}>{header}</Heading>
-            </span>
+            <Heading level={2} xstyle={styles.headerText}>
+              {header}
+            </Heading>
           ) : (
             (header ?? null)
           )}

package/src/MoreMenu/MoreMenu.doc.mjs

@@ -47,6 +47,20 @@ export const docs = {
       description: 'Whether the menu trigger is disabled.',
       default: 'false',
     },    {
+      name: 'placement',
+      type: "'above' | 'below' | 'start' | 'end'",
+      description:
+        "Position of the menu relative to the trigger. Logical: start/end resolve against the menu's own inherited direction (RTL mirrors).",
+      default: "'below'",
+    },
+    {
+      name: 'alignment',
+      type: "'start' | 'center' | 'end'",
+      description:
+        "Alignment along the placement axis. Use 'end' to align the menu with the trigger's trailing edge, which is usually what an overflow menu wants.",
+      default: "'start'",
+    },
+    {
       name: 'xstyle',
       type: 'StyleXStyles',
       description:
@@ -120,6 +134,20 @@ export const docsZh = {
       description: '菜单触发器是否禁用。',
       default: 'false',
     },    {
+      name: 'placement',
+      type: "'above' | 'below' | 'start' | 'end'",
+      description:
+        '菜单相对于触发按钮的位置。逻辑方向：start/end 依据菜单自身继承的书写方向解析（RTL 自动镜像）。',
+      default: "'below'",
+    },
+    {
+      name: 'alignment',
+      type: "'start' | 'center' | 'end'",
+      description:
+        "沿放置轴的对齐方式。使用 'end' 让菜单与触发器的尾部边缘对齐，这通常是溢出菜单所需的效果。",
+      default: "'start'",
+    },
+    {
       name: 'xstyle',
       type: 'StyleXStyles',
       description:
@@ -162,6 +190,9 @@ export const docsDense = {
     size: 'Trigger button size.',
     icon: 'Override default three-dot icon. Accepts any ReactNode.',
     isDisabled: 'Whether menu trigger disabled.',
+    placement: 'Menu position relative to trigger. Logical (RTL mirrors).',
+    alignment:
+      "Alignment along the placement axis. 'end' aligns with the trigger's trailing edge.",
     xstyle:
       'StyleX styles for layout customization (margins, positioning, sizing). Must be stylex.create() value.',
   },

package/src/MoreMenu/MoreMenu.test.tsx

@@ -10,9 +10,10 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {MoreMenu} from './MoreMenu';
+import {DropdownMenu} from '../DropdownMenu/DropdownMenu';
 
 // Mock showPopover and hidePopover methods since they're not implemented in jsdom
 beforeEach(() => {
@@ -197,4 +198,70 @@ describe('MoreMenu', () => {
     const menu = screen.getByRole('menu', {hidden: true});
     expect(menu.className).toContain('astryx-more-menu');
   });
+
+  it('pointer open focuses the menu container, not the first item (#4477)', async () => {
+    const user = userEvent.setup();
+    render(<MoreMenu items={defaultItems} />);
+
+    await user.click(screen.getByRole('button', {name: 'More options'}));
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    await waitFor(() => expect(menu).toHaveFocus());
+    expect(
+      screen.getByRole('menuitem', {name: 'Edit', hidden: true}),
+    ).not.toHaveFocus();
+  });
+
+  it('first ArrowDown after a pointer open moves focus to the first item (#4477)', async () => {
+    const user = userEvent.setup();
+    render(<MoreMenu items={defaultItems} />);
+
+    await user.click(screen.getByRole('button', {name: 'More options'}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    await waitFor(() => expect(menu).toHaveFocus());
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitem', {name: 'Edit', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  describe('placement and alignment', () => {
+    const positionAreaOf = (menu: HTMLElement) =>
+      menu
+        .closest('[popover]')
+        ?.getAttribute('style')
+        ?.match(/position-area:[^;]*/)?.[0];
+
+    it('resolves the same default position as DropdownMenu', () => {
+      render(
+        <>
+          <MoreMenu items={defaultItems} />
+          <DropdownMenu button={{label: 'Actions'}} items={defaultItems} />
+        </>,
+      );
+      const [moreMenu, dropdownMenu] = screen.getAllByRole('menu', {
+        hidden: true,
+      });
+
+      expect(positionAreaOf(moreMenu)).toBe(positionAreaOf(dropdownMenu));
+      expect(positionAreaOf(moreMenu)).toBe(
+        'position-area: self-block-end span-self-inline-end',
+      );
+    });
+
+    it('forwards alignment to the menu layer', () => {
+      render(<MoreMenu items={defaultItems} alignment="end" />);
+      expect(positionAreaOf(screen.getByRole('menu', {hidden: true}))).toBe(
+        'position-area: self-block-end span-self-inline-start',
+      );
+    });
+
+    it('forwards placement to the menu layer', () => {
+      render(<MoreMenu items={defaultItems} placement="above" />);
+      expect(positionAreaOf(screen.getByRole('menu', {hidden: true}))).toBe(
+        'position-area: self-block-start span-self-inline-end',
+      );
+    });
+  });
 });

package/src/MoreMenu/MoreMenu.tsx

@@ -23,6 +23,7 @@ import {useIcon} from '../Icon';
 import {DropdownMenu} from '../DropdownMenu/DropdownMenu';
 import {useSize} from '../SizeContext/SizeContext';
 import type {DropdownMenuOption} from '../DropdownMenu';
+import type {LayerAlignment, LayerPlacement} from '../Layer';
 import type {ButtonVariant, ButtonSize} from '../Button';
 import type {BaseProps} from '../BaseProps';
 import {stableClassName} from '../naming';
@@ -72,6 +73,20 @@ export interface MoreMenuProps extends Pick<
    */
   isDisabled?: boolean;
 
+  /**
+   * Position of the menu relative to the trigger button.
+   * Forwarded to DropdownMenu, which owns the default.
+   * @default 'below'
+   */
+  placement?: LayerPlacement;
+
+  /**
+   * Alignment of the menu along the placement axis.
+   * Forwarded to DropdownMenu, which owns the default.
+   * @default 'start'
+   */
+  alignment?: LayerAlignment;
+
   /**
    * Controlled open state for the menu.
    */
@@ -108,6 +123,8 @@ export function MoreMenu({
   size: sizeProp,
   icon,
   isDisabled = false,
+  placement,
+  alignment,
   isMenuOpen,
   onOpenChange,
   xstyle,
@@ -132,6 +149,8 @@ export function MoreMenu({
       style={style}
       isMenuOpen={isMenuOpen}
       onOpenChange={onOpenChange}
+      placement={placement}
+      alignment={alignment}
       button={{
         label,
         icon: icon ?? moreIcon,

package/src/MultiSelector/MultiSelector.doc.mjs

@@ -23,12 +23,22 @@ export const docs = {
       {
         className: 'astryx-multi-selector',
         visualProps: ['variant', 'size', 'status'],
+        states: ['disabled'],
       },
-      {className: 'astryx-multi-selector-clear-icon'},
+      {className: 'astryx-multi-selector-clear-icon', deprecatedFor: 'input-clear-icon'},
+      {className: 'astryx-multi-selector-empty-state'},
+      {className: 'astryx-multi-selector-search'},
+      {className: 'astryx-multi-selector-section-heading'},
       {
         className: 'astryx-multi-selector-indicator-icon',
         states: ['state'],
       },
+      {
+        className: 'astryx-multi-selector-option',
+        visualProps: ['size'],
+        states: ['select-all', 'selected', 'disabled'],
+      },
+      {className: 'astryx-multi-selector-popup'},
     ],
   },
   components: [
@@ -184,6 +194,13 @@ export const docs = {
           description:
             'Custom render function for each selectable option in the dropdown. Not called for dividers, sections, or the select-all row.',
         },
+        {
+          name: 'indicatorPosition',
+          type: "'start' | 'end'",
+          description:
+            'Which edge of the option row carries the checkbox. end pushes it to the far edge of the row, including on the select-all row.',
+          default: "'start'",
+        },
         {
           name: 'width',
           type: 'SizeValue',