@astryxdesign/core 0.2.0 → 0.3.0-canary.1b8b3f2

package/src/Dialog/Dialog.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Dialog/Dialog.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Dialog/index.ts (exports if types change)
  * - /apps/storybook/stories/Dialog.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Dialog/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Dialog/ (showcase blocks)
  */
 
 import {
@@ -49,6 +49,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {devWarn} from '../utils/devWarning';
 import {DialogContext} from './DialogContext';
 import {themeProps} from '../utils/themeProps';
+import type {DialogVariantMap} from './index';
 
 /**
  * Calculate a directional translate offset for dialog entry animation.
@@ -69,24 +70,6 @@ function getDialogDirection(
   };
 }
 
-/**
- * Extensible variant map for Dialog.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/Dialog' {
- *   interface DialogVariantMap {
- *     'drawer': true;
- *   }
- * }
- * ```
- */
-export interface DialogVariantMap {
-  standard: true;
-  fullscreen: true;
-}
-
 /**
  * Dialog variant type
  * - standard: Normal dialog with configurable width/height
@@ -104,14 +87,23 @@ export type DialogVariant = keyof DialogVariantMap;
  */
 export type DialogPurpose = 'required' | 'form' | 'info';
 
+/** Block-axis offsets — always allowed, independent of inline direction. */
+interface DialogBlockPosition {
+  top?: number | string;
+  bottom?: number | string;
+}
+
 /**
- * Position configuration for static dialog positioning
+ * Static position for a dialog. The inline axis is logical XOR physical — the
+ * type forbids mixing the two, so a single dialog can't be positioned both ways:
+ * - Logical `start`/`end` map to `inset-inline-*` and mirror under RTL (preferred).
+ * Block-axis `top`/`bottom` may be combined with either.
  */
-export interface DialogPosition {
-  bottom?: number | string;
-  left?: number | string;
-  right?: number | string;
-  top?: number | string;
+export interface DialogPosition extends DialogBlockPosition {
+  /** Logical inline-start offset (`inset-inline-start`); mirrors under RTL. */
+  start?: number | string;
+  /** Logical inline-end offset (`inset-inline-end`); mirrors under RTL. */
+  end?: number | string;
 }
 
 const enterDirectional = stylex.keyframes({
@@ -215,30 +207,52 @@ const dynamicStyles = stylex.create({
     maxHeight: typeof maxHeight === 'number' ? `${maxHeight}px` : maxHeight,
   }),
   position: (
-    top: number | string | undefined,
-    right: number | string | undefined,
-    bottom: number | string | undefined,
-    left: number | string | undefined,
+    top: string,
+    insetInlineStart: string,
+    insetInlineEnd: string,
+    bottom: string,
   ) => ({
-    // When position is set, disable auto margin and use fixed positioning
+    // Assigns pre-resolved offsets from resolveDialogPositionOffsets(). This
+    // literal has no logic — StyleX can't analyze a helper, so the values
+    // (logical start/end → inset-inline-*, physical left/right, `auto`
+    // fallbacks) are computed at the call site and passed in.
     margin: 0,
-    top: top !== undefined ? formatPosition(top) : 'auto',
-    right: right !== undefined ? formatPosition(right) : 'auto',
-    bottom: bottom !== undefined ? formatPosition(bottom) : 'auto',
-    left: left !== undefined ? formatPosition(left) : 'auto',
+    top,
+    insetInlineStart,
+    insetInlineEnd,
+    bottom,
   }),
 });
 
 /**
  * Format position value - numbers become pixels, strings pass through, undefined becomes null
  */
-function formatPosition(value: number | string | undefined): string | null {
-  if (value === undefined) {
-    return null;
-  }
+function formatPosition(value: number | string): string {
   return typeof value === 'number' ? `${value}px` : value;
 }
 
+/**
+ * Map a {@link DialogPosition} to resolved CSS offsets. Logical `start`/`end`
+ * become `inset-inline-*` (mirror under RTL); each unset offset falls back to
+ * `auto`.
+ *
+ * Not re-exported from the package; internal to Dialog. Directly unit-tested
+ * so the mapping is verified without StyleX class compilation.
+ *
+ * @see DialogPosition
+ */
+export function resolveDialogPositionOffsets(position: DialogPosition) {
+  const {top, bottom, start, end} = position;
+
+  return {
+    top: top !== undefined ? formatPosition(top) : 'auto',
+    bottom: bottom !== undefined ? formatPosition(bottom) : 'auto',
+    // Logical offsets mirror under RTL (preferred replacements).
+    insetInlineStart: start !== undefined ? formatPosition(start) : 'auto',
+    insetInlineEnd: end !== undefined ? formatPosition(end) : 'auto',
+  };
+}
+
 export interface DialogProps extends BaseProps<HTMLDialogElement> {
   /** Ref forwarded to the root element */
   ref?: React.Ref<HTMLDialogElement>;
@@ -632,12 +646,15 @@ export function Dialog({
           styles.backdrop,
           !isFullscreen && dynamicStyles.sizing(width, maxHeight),
           hasPosition &&
-            dynamicStyles.position(
-              position?.top,
-              position?.right,
-              position?.bottom,
-              position?.left,
-            ),
+            (() => {
+              const o = resolveDialogPositionOffsets(position);
+              return dynamicStyles.position(
+                o.top,
+                o.insetInlineStart,
+                o.insetInlineEnd,
+                o.bottom,
+              );
+            })(),
           isFullscreen && styles.fullscreen,
           xstyle,
         ),

package/src/Dialog/DialogHeader.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DialogHeader',

package/src/Dialog/DialogHeader.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Dialog/DialogHeader.test.tsx
  * - /packages/core/src/Dialog/index.ts
  * - /apps/storybook/stories/Dialog.stories.tsx
- * - /packages/cli/templates/blocks/components/Dialog/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Dialog/ (showcase blocks)
  */
 
 import {useEffect, useRef, type ReactNode} from 'react';

package/src/Dialog/index.ts

@@ -11,11 +11,28 @@
  * SYNC: When modified, update this header and /packages/core/src/Dialog/Dialog.doc.mjs
  */
 
+/**
+ * Extensible variant map for Dialog.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Dialog' {
+ *   interface DialogVariantMap {
+ *     'drawer': true;
+ *   }
+ * }
+ * ```
+ */
+export interface DialogVariantMap {
+  standard: true;
+  fullscreen: true;
+}
+
 export {Dialog} from './Dialog';
 export type {
   DialogProps,
   DialogVariant,
-  DialogVariantMap,
   DialogPurpose,
   DialogPosition,
 } from './Dialog';

package/src/Dialog/useImperativeDialog.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'useImperativeDialog',

package/src/Divider/Divider.doc.mjs

@@ -2,7 +2,7 @@
 
 
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Divider',
@@ -56,7 +56,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Divider',
   displayName: 'Divider',
@@ -106,7 +106,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'visual separator w/ optional label, using Astryx design tokens',
   usage: {

package/src/Divider/Divider.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/Divider/Divider.doc.mjs
  * - /packages/core/src/Divider/Divider.test.tsx
  * - /apps/storybook/stories/Divider.stories.tsx
- * - /packages/cli/templates/blocks/components/Divider/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Divider/ (showcase blocks)
  */
 
 import {useId, type ReactNode} from 'react';
@@ -27,24 +27,7 @@ import {
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
-
-/**
- * Extensible variant map for Divider.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/Divider' {
- *   interface DividerVariantMap {
- *     'accent': true;
- *   }
- * }
- * ```
- */
-export interface DividerVariantMap {
-  subtle: true;
-  strong: true;
-}
+import type {DividerVariantMap} from './index';
 
 /**
  * Divider variant type. Extensible via module augmentation of DividerVariantMap.

package/src/Divider/index.ts

@@ -11,9 +11,23 @@
  * SYNC: When modified, update /packages/core/src/Divider/Divider.doc.mjs
  */
 
+/**
+ * Extensible variant map for Divider.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Divider' {
+ *   interface DividerVariantMap {
+ *     'accent': true;
+ *   }
+ * }
+ * ```
+ */
+export interface DividerVariantMap {
+  subtle: true;
+  strong: true;
+}
+
 export {Divider} from './Divider';
-export type {
-  DividerProps,
-  DividerVariant,
-  DividerVariantMap,
-} from './Divider';
+export type {DividerProps, DividerVariant} from './Divider';

package/src/DropdownMenu/DropdownMenu.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DropdownMenu',
@@ -26,15 +26,18 @@ export const docs = {
       {className: 'astryx-dropdown-menu'},
       {className: 'astryx-dropdown-menu-item', visualProps: ['size']},
       {
-        className: 'astryx-dropdown-menu-checkbox',
+        className: 'astryx-dropdown-menu-radio',
         visualProps: ['size'],
         states: ['checked', 'disabled'],
       },
       {
-        className: 'astryx-dropdown-menu-radio',
+        className: 'astryx-dropdown-menu-radio-dot',
         visualProps: ['size'],
         states: ['checked', 'disabled'],
       },
+      {className: 'astryx-dropdown-menu-section-heading'},
+      {className: 'astryx-dropdown-menu-divider'},
+      {className: 'astryx-dropdown-menu-indicator-icon'},
     ],
     vars: [
       {name: '--_dropdown-menu-radius', description: 'Border radius of the menu popup', default: 'var(--radius-element)', private: true},
@@ -74,6 +77,18 @@ export const docs = {
       type: 'number | string',
       description: 'Custom menu width; defaults to matching the trigger button width.',
     },
+    {
+      name: 'placement',
+      type: "'above' | 'below' | 'start' | 'end'",
+      description: "Position placement 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. Logical: start/end follow the menu's own inherited direction (RTL mirrors).",
+      default: "'start'",
+    },
     {
       name: 'onClick',
       type: '() => void',
@@ -104,7 +119,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: 'A dropdown menu that displays a list of actionable items in a popup triggered by a button. Use to present action options as a next step in a process, or to offer contextual actions without cluttering the interface.',
@@ -117,7 +132,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'dropdown menu for actionable items in popup',
   usage: {

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -109,6 +109,22 @@ describe('DropdownMenu', () => {
     );
   });
 
+  it('supports explicit menu alignment', () => {
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        alignment="end"
+        items={[{label: 'Item 1'}]}
+      />,
+    );
+    const popover = screen
+      .getByRole('menu', {hidden: true})
+      .closest('[popover]');
+    expect(popover?.getAttribute('style')).toContain(
+      'position-area: self-block-end span-self-inline-start',
+    );
+  });
+
   it('emits the direction-independent logical mapping under an RTL ancestor (#3389)', async () => {
     // The self-* position-area keywords resolve against the popover's own
     // inherited direction in the browser, so RTL emits the same string as
@@ -148,6 +164,77 @@ describe('DropdownMenu', () => {
     expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
   });
 
+  it('calls onOpenChange for uncontrolled native open and close transitions', async () => {
+    const user = userEvent.setup();
+    const handleOpenChange = vi.fn();
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        items={[{label: 'Item 1'}]}
+        onOpenChange={handleOpenChange}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    expect(handleOpenChange).toHaveBeenCalledWith(true);
+
+    handleOpenChange.mockClear();
+    const popoverEl = screen
+      .getByRole('menu', {hidden: true})
+      .closest('[popover]');
+    expect(popoverEl).not.toBeNull();
+    const toggleEvent = new Event('toggle');
+    Object.defineProperty(toggleEvent, 'newState', {value: 'closed'});
+    fireEvent(popoverEl as HTMLElement, toggleEvent);
+
+    expect(handleOpenChange).toHaveBeenCalledWith(false);
+    expect(screen.getByRole('button', {name: /Actions/})).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
+  });
+
+  it('restores focus to the trigger after native light dismiss', async () => {
+    const raf = vi
+      .spyOn(window, 'requestAnimationFrame')
+      .mockImplementation(callback => {
+        callback(0);
+        return 0;
+      });
+
+    try {
+      const user = userEvent.setup();
+      render(
+        <DropdownMenu
+          button={{label: 'Actions'}}
+          items={[{label: 'Edit'}, {label: 'Delete'}]}
+        />,
+      );
+
+      const trigger = screen.getByRole('button', {name: /Actions/});
+      trigger.focus();
+      await user.click(trigger);
+      expect(
+        screen.getByRole('menuitem', {name: 'Edit', hidden: true}),
+      ).toHaveFocus();
+
+      const popoverEl = screen
+        .getByRole('menu', {hidden: true})
+        .closest('[popover]');
+      expect(popoverEl).not.toBeNull();
+      popoverEl?.addEventListener('toggle', () => {
+        trigger.blur();
+      });
+      const toggleEvent = new Event('toggle');
+      Object.defineProperty(toggleEvent, 'newState', {value: 'closed'});
+      fireEvent(popoverEl as HTMLElement, toggleEvent);
+
+      expect(trigger).toHaveFocus();
+    } finally {
+      raf.mockRestore();
+    }
+  });
+
   it('closes the menu when Tab is pressed inside it (APG menu-button)', async () => {
     const user = userEvent.setup();
     render(
@@ -415,6 +502,41 @@ describe('DropdownMenu dividers', () => {
   });
 });
 
+describe('DropdownMenu theming slots', () => {
+  it('exposes a themeable slot on the section heading', () => {
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        items={[
+          {
+            type: 'section',
+            title: 'File Actions',
+            items: [{label: 'New'}],
+          },
+        ]}
+      />,
+    );
+
+    expect(screen.getByText('File Actions')).toHaveClass(
+      'astryx-dropdown-menu-section-heading',
+    );
+  });
+
+  it('exposes a themeable slot on the menu divider', () => {
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        items={[{label: 'Edit'}, {type: 'divider'}, {label: 'Delete'}]}
+      />,
+    );
+
+    const divider = screen.getByRole('separator', {hidden: true});
+    expect(divider).toHaveClass('astryx-dropdown-menu-divider');
+    // Still carries the base Divider slot so global divider theming applies too.
+    expect(divider).toHaveClass('astryx-divider');
+  });
+});
+
 describe('DropdownMenu button customization', () => {
   it('renders with different button variants', () => {
     const {rerender} = render(

package/src/DropdownMenu/DropdownMenu.tsx

@@ -19,7 +19,7 @@
  * - /packages/core/src/DropdownMenu/DropdownMenu.test.tsx
  * - /packages/core/src/DropdownMenu/index.ts
  * - /apps/storybook/stories/DropdownMenu.stories.tsx
- * - /packages/cli/templates/blocks/components/DropdownMenu/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/DropdownMenu/ (showcase blocks)
  */
 
 import React, {
@@ -50,7 +50,7 @@ import {
 import {useListFocus} from '../hooks/useListFocus';
 import {useTypeahead} from '../hooks/useTypeahead';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
-import type {LayerPlacement} from '../Layer/useLayer';
+import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {
   spacingVars,
   radiusVars,
@@ -145,6 +145,13 @@ interface DropdownMenuBaseProps extends BaseProps {
    */
   placement?: LayerPlacement;
 
+  /**
+   * Alignment along the placement axis.
+   * Uses the same alignment values as other Astryx layer-based components.
+   * @default 'start'
+   */
+  alignment?: LayerAlignment;
+
   'data-testid'?: string;
 }
 
@@ -198,6 +205,7 @@ export function DropdownMenu({
   onClick,
   hasChevron = true,
   placement = 'below',
+  alignment = 'start',
   className,
   style,
   xstyle,
@@ -235,28 +243,22 @@ export function DropdownMenu({
   // Close menu + return focus to trigger
   const handleLayerHide = useCallback(() => {
     lastHideTimeRef.current = Date.now();
-    if (isControlled) {
-      onOpenChange?.(false);
-    } else {
+    onOpenChange?.(false);
+    if (!isControlled) {
       setInternalIsOpen(false);
     }
     buttonRef.current?.focus();
   }, [isControlled, onOpenChange]);
 
-  // Track whether to focus the first item when the menu opens
+  // Defer item focus until the layer has committed open, so focus restore
+  // captures the trigger instead of the first menu item.
   const shouldFocusOnOpenRef = useRef(false);
 
   const handleLayerShow = useCallback(() => {
-    if (isControlled) {
-      onOpenChange?.(true);
-    } else {
+    onOpenChange?.(true);
+    if (!isControlled) {
       setInternalIsOpen(true);
     }
-    if (shouldFocusOnOpenRef.current) {
-      shouldFocusOnOpenRef.current = false;
-      // focusFirst is called via openAndFocus below — defer to rAF
-      // so the popover content is rendered before we query for items
-    }
   }, [isControlled, onOpenChange]);
 
   const popover = usePopover({
@@ -305,17 +307,26 @@ export function DropdownMenu({
       ),
   });
 
-  // Sync controlled open state → popover, and focus first item on open
+  // Sync controlled open state → popover.
   useEffect(() => {
     if (isControlled) {
       if (controlledIsOpen && !popover.isOpen) {
+        shouldFocusOnOpenRef.current = true;
         popover.show();
-        requestAnimationFrame(() => focusFirst());
       } else if (!controlledIsOpen && popover.isOpen) {
         popover.hide();
       }
     }
-  }, [controlledIsOpen, isControlled, popover, focusFirst]);
+  }, [controlledIsOpen, isControlled, popover]);
+
+  // Move focus into the menu only after the layer has committed open.
+  useEffect(() => {
+    if (!popover.isOpen || !shouldFocusOnOpenRef.current) {
+      return;
+    }
+    shouldFocusOnOpenRef.current = false;
+    requestAnimationFrame(() => focusFirst());
+  }, [popover.isOpen, focusFirst]);
 
   // Extend useListFocus with Enter/Space activation + typeahead
   const listKeyDown = useCallback(
@@ -356,9 +367,9 @@ export function DropdownMenu({
   );
 
   const openAndFocus = useCallback(() => {
+    shouldFocusOnOpenRef.current = true;
     popover.show();
-    requestAnimationFrame(() => focusFirst());
-  }, [popover, focusFirst]);
+  }, [popover]);
 
   const handleButtonClick = useCallback(() => {
     // If the menu was just closed by light dismiss (e.g. iOS Safari fires
@@ -474,7 +485,7 @@ export function DropdownMenu({
         </div>,
         {
           placement,
-          alignment: 'start',
+          alignment,
           xstyle: [popoverXstyle, popoverGapStyle, layerAnimations[placement]],
         },
       )}

package/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'DropdownMenuCheckboxItem',