@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/ComplexSelector/ComplexSelector.tsx

@@ -0,0 +1,443 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ComplexSelector.tsx
+ * @input Uses React, StyleX, Field, usePopover
+ * @output Exports ComplexSelector component for custom selector surfaces
+ * @position Core implementation; consumed by index.ts
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/ComplexSelector/ComplexSelector.doc.mjs
+ * - /packages/core/src/ComplexSelector/ComplexSelector.test.tsx
+ * - /packages/core/src/ComplexSelector/index.ts
+ * - /apps/storybook/stories/ComplexSelector.stories.tsx
+ */
+
+import React, {
+  useCallback,
+  useId,
+  useOptimistic,
+  useTransition,
+  type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {Field, inputWrapperStyles, type FieldStatusVariant} from '../Field';
+import {Icon} from '../Icon';
+import {Spinner} from '../Spinner';
+import {useTranslator} from '../i18n';
+import {layerAnimations} from '../Layer/layerAnimations.stylex';
+import {usePopover} from '../Popover/usePopover';
+import {
+  colorVars,
+  durationVars,
+  easeVars,
+  radiusVars,
+  sizeVars,
+  spacingVars,
+  typographyVars,
+  typeScaleVars,
+} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+import type {SizeValue} from '../utils/types';
+import {themeProps} from '../utils/themeProps';
+
+const styles = stylex.create({
+  triggerContainer: {
+    position: 'relative',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: spacingVars['--spacing-2'],
+    width: '100%',
+    paddingBlock: spacingVars['--spacing-2'],
+    paddingInline: spacingVars['--spacing-3'],
+    fontFamily: typographyVars['--font-family-body'],
+    fontSize: {
+      default: typeScaleVars['--text-label-size'],
+      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+    },
+    lineHeight: typeScaleVars['--text-label-leading'],
+    color: colorVars['--color-text-primary'],
+    cursor: 'pointer',
+  },
+  trigger: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: spacingVars['--spacing-2'],
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: 0,
+    minWidth: 0,
+    padding: 0,
+    margin: 0,
+    borderWidth: 0,
+    borderStyle: 'none',
+    backgroundColor: 'transparent',
+    fontFamily: 'inherit',
+    fontSize: 'inherit',
+    lineHeight: 'inherit',
+    color: 'inherit',
+    cursor: 'pointer',
+    outline: 'none',
+    borderRadius: radiusVars['--radius-element'],
+  },
+  triggerText: {
+    flexGrow: 1,
+    minWidth: 0,
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    whiteSpace: 'nowrap',
+    textAlign: 'start',
+  },
+  placeholder: {
+    color: colorVars['--color-text-secondary'],
+  },
+  // Only what Icon does not already provide: `sm` gives the 16px box and
+  // `color="secondary"` the color, but the glyph still must not shrink inside
+  // the flex trigger.
+  triggerIcon: {
+    flexShrink: 0,
+  },
+  // Rotation lives on the chevron glyph itself (passed through `xstyle`), not
+  // on the layout wrapper above, so the icon's
+  // `complex-selector-indicator-icon` theme target and the open/closed
+  // transform sit on one element — a theme can restyle the mark and its
+  // rotation through a single selector. The wrapper keeps only layout.
+  triggerIconRotation: {
+    transitionProperty: 'transform',
+    transitionDuration: durationVars['--duration-fast'],
+    transitionTimingFunction: easeVars['--ease-standard'],
+    transformOrigin: 'center',
+  },
+  triggerIconOpen: {
+    transform: 'rotate(180deg)',
+  },
+  popover: {
+    minWidth: 'anchor-size(width)',
+    // Both edges, not just the start: this popup can open either direction
+    // (`placement="below"` or `"above"`), and only marginBlockStart having a
+    // value meant the clearance vanished when it opened upward, since that's
+    // the edge nearest the trigger in that orientation. Popover (built on
+    // the same usePopover/useLayer pair) sets both edges for the same
+    // reason — see its `gap` style.
+    marginBlockStart: spacingVars['--spacing-1'],
+    marginBlockEnd: spacingVars['--spacing-1'],
+  },
+  content: {
+    boxSizing: 'border-box',
+    maxHeight: 'min(480px, calc(100vh - 32px))',
+    overflow: 'auto',
+    padding: spacingVars['--spacing-3'],
+  },
+  sm: {
+    minHeight: sizeVars['--size-element-sm'],
+  },
+  md: {
+    minHeight: sizeVars['--size-element-md'],
+  },
+  lg: {
+    minHeight: sizeVars['--size-element-lg'],
+  },
+  disabled: {
+    cursor: 'not-allowed',
+  },
+  focusRing: {
+    ':focus-within': {
+      outline: `2px solid ${colorVars['--color-accent']}`,
+      outlineOffset: '2px',
+    },
+  },
+});
+
+export type ComplexSelectorSize = 'sm' | 'md' | 'lg';
+
+export interface ComplexSelectorRenderState {
+  /** Whether the selector surface is open. */
+  isOpen: boolean;
+  /** Whether changeAction/isLoading is pending. */
+  isBusy: boolean;
+  /** ID of the trigger button. */
+  triggerId: string;
+  /** ID of the popup content container. */
+  contentId: string;
+}
+
+export interface ComplexSelectorStatus {
+  type: 'warning' | 'error' | 'success';
+  message?: string;
+}
+
+export interface ComplexSelectorProps<Value> extends Omit<
+  BaseProps<HTMLDivElement>,
+  'children' | 'onChange'
+> {
+  /** Label text for accessibility and the field label. */
+  label: string;
+  /** Current controlled value. */
+  value: Value;
+  /** Called when custom content commits a new value. */
+  onChange?: (value: Value) => void;
+  /** Optional async action after onChange; drives optimistic UI. */
+  changeAction?: (value: Value) => void | Promise<void>;
+  /** Custom selector surface content rendered inside a dialog popover. */
+  children: (
+    value: Value,
+    onChange: (value: Value) => void,
+    close: () => void,
+    state: ComplexSelectorRenderState,
+  ) => ReactNode;
+  /** Label/content shown in the closed trigger. */
+  triggerLabel?: ReactNode;
+  /** Placeholder shown when triggerLabel is omitted. */
+  placeholder?: ReactNode;
+  /** Whether to visually hide the field label. */
+  isLabelHidden?: boolean;
+  /** Helper text displayed below the label. */
+  description?: string;
+  /** Marks the field optional. */
+  isOptional?: boolean;
+  /** Marks the field required. */
+  isRequired?: boolean;
+  /** Disables the selector. */
+  isDisabled?: boolean;
+  /** Shows loading state on the trigger. */
+  isLoading?: boolean;
+  /** Validation status. */
+  status?: ComplexSelectorStatus;
+  /** Status placement. */
+  statusVariant?: FieldStatusVariant;
+  /** Tooltip text displayed next to the label. */
+  labelTooltip?: string;
+  /** Trigger and field size. */
+  size?: ComplexSelectorSize;
+  /** Width of the field. */
+  width?: SizeValue;
+  /** Popup placement. */
+  placement?: 'above' | 'below' | 'start' | 'end';
+  /** StyleX styles for the popup content container. */
+  contentXstyle?: StyleXStyles;
+  /** Test ID for the trigger container. */
+  'data-testid'?: string;
+}
+
+/**
+ * A selector shell for rich, custom selection surfaces.
+ *
+ * ComplexSelector owns the field, trigger, popover, focus restore, and async
+ * change action flow. Consumers provide the dialog content as a render function,
+ * using the supplied `value`, `onChange`, and `close` helpers to compose the
+ * right accessible structure for the custom selector.
+ *
+ * @example
+ * ```
+ * <ComplexSelector
+ *   label="Fruit"
+ *   value={value}
+ *   onChange={setValue}
+ *   triggerLabel={`${value.fruit} ${value.ripeness}`}>
+ *   {(value, onChange, close) => (
+ *     <FruitGrid
+ *       value={value}
+ *       onChange={nextValue => {
+ *         onChange(nextValue);
+ *         close();
+ *       }}
+ *     />
+ *   )}
+ * </ComplexSelector>
+ * ```
+ */
+export function ComplexSelector<Value>({
+  label,
+  value,
+  onChange,
+  changeAction,
+  children,
+  triggerLabel,
+  placeholder: placeholderFromProps,
+  isLabelHidden = false,
+  description,
+  isOptional = false,
+  isRequired = false,
+  isDisabled = false,
+  isLoading = false,
+  status,
+  statusVariant = 'attached',
+  labelTooltip,
+  size = 'md',
+  width,
+  placement = 'below',
+  contentXstyle,
+  xstyle,
+  className,
+  style,
+  'data-testid': testId,
+  ...props
+}: ComplexSelectorProps<Value>) {
+  const t = useTranslator();
+  const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
+
+  const triggerId = useId();
+  const labelId = useId();
+  const contentId = useId();
+  const descriptionId = useId();
+  const statusMessageId = useId();
+  const ariaDescribedBy =
+    [
+      description ? descriptionId : null,
+      status?.message ? statusMessageId : null,
+    ]
+      .filter((id): id is string => id != null)
+      .join(' ') || undefined;
+
+  const [isPending, startTransition] = useTransition();
+  const [optimisticValue, setOptimisticValue] = useOptimistic(value);
+  const isBusy = isLoading || isPending;
+
+  const popover = usePopover({
+    dialogLabel: label,
+    hasCloseButton: false,
+    hasAutoFocus: true,
+    onHide: () => {
+      document.getElementById(triggerId)?.focus();
+    },
+  });
+
+  const commitValue = useCallback(
+    (nextValue: Value) => {
+      onChange?.(nextValue);
+      if (changeAction) {
+        startTransition(async () => {
+          setOptimisticValue(nextValue);
+          await changeAction(nextValue);
+        });
+      }
+    },
+    [changeAction, onChange, setOptimisticValue, startTransition],
+  );
+
+  const triggerContent = triggerLabel ?? placeholder;
+
+  const content = (
+    <div id={contentId} {...stylex.props(styles.content, contentXstyle)}>
+      {children(optimisticValue, commitValue, popover.hide, {
+        isOpen: popover.isOpen,
+        isBusy,
+        triggerId,
+        contentId,
+      })}
+    </div>
+  );
+
+  const selectorContent = (
+    <>
+      <div
+        ref={popover.triggerRef}
+        data-testid={testId}
+        {...props}
+        onClick={() => {
+          if (!isDisabled) {
+            popover.toggle();
+          }
+        }}
+        {...mergeProps(
+          themeProps('complex-selector', {
+            size,
+            status: status?.type ?? null,
+          }),
+          stylex.props(
+            inputWrapperStyles.base,
+            styles.triggerContainer,
+            styles[size],
+            styles.focusRing,
+            isDisabled && inputWrapperStyles.disabled,
+            isDisabled && styles.disabled,
+            triggerLabel == null && styles.placeholder,
+            xstyle,
+          ),
+          className,
+          style,
+        )}>
+        <button
+          id={triggerId}
+          type="button"
+          aria-haspopup="dialog"
+          aria-expanded={popover.isOpen}
+          aria-controls={contentId}
+          aria-describedby={ariaDescribedBy}
+          aria-labelledby={labelId}
+          aria-required={isRequired ? 'true' : undefined}
+          aria-invalid={status?.type === 'error' ? 'true' : undefined}
+          aria-busy={isBusy || undefined}
+          disabled={isDisabled}
+          onKeyDown={event => {
+            if (event.key === 'ArrowDown' && !popover.isOpen && !isDisabled) {
+              event.preventDefault();
+              popover.show();
+            }
+          }}
+          {...stylex.props(styles.trigger)}>
+          <span {...stylex.props(styles.triggerText)}>{triggerContent}</span>
+        </button>
+        {isBusy && <Spinner size="sm" />}
+        <Icon
+          icon="chevronDown"
+          size="sm"
+          color="secondary"
+          // No wrapper: Icon's own span already provides the 16px box (`sm`)
+          // and the secondary icon color the wrapper used to set, so the glyph
+          // IS the trigger's icon element — one node carrying the box, the
+          // color, the rotation, and the theme target.
+          xstyle={[
+            styles.triggerIcon,
+            styles.triggerIconRotation,
+            popover.isOpen && styles.triggerIconOpen,
+          ]}
+          {...themeProps('complex-selector-indicator-icon', {
+            state: popover.isOpen ? 'expanded' : 'collapsed',
+          })}
+        />
+      </div>
+
+      {popover.render(content, {
+        placement,
+        alignment: 'start',
+        xstyle: [styles.popover, layerAnimations[placement]],
+      })}
+    </>
+  );
+
+  return (
+    <Field
+      label={label}
+      isLabelHidden={isLabelHidden}
+      description={description}
+      inputID={triggerId}
+      descriptionID={description ? descriptionId : undefined}
+      labelID={labelId}
+      isOptional={isOptional}
+      isRequired={isRequired}
+      isDisabled={isDisabled}
+      status={
+        status
+          ? {
+              type: status.type,
+              message: status.message,
+              messageID: status.message ? statusMessageId : undefined,
+            }
+          : undefined
+      }
+      statusVariant={statusVariant}
+      labelTooltip={labelTooltip}
+      width={width}>
+      {selectorContent}
+    </Field>
+  );
+}
+
+ComplexSelector.displayName = 'ComplexSelector';

package/src/ComplexSelector/index.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @output Exports ComplexSelector and types
+ * @position Public API entry point
+ */
+
+export {
+  ComplexSelector,
+  type ComplexSelectorProps,
+  type ComplexSelectorRenderState,
+  type ComplexSelectorSize,
+  type ComplexSelectorStatus,
+} from './ComplexSelector';

package/src/ContextMenu/ContextMenu.doc.mjs

@@ -1,5 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'ContextMenu',
@@ -32,7 +32,7 @@ export const docs = {
     {
       name: 'items',
       type: 'ContextMenuOption[]',
-      description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?}`, a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
+      description: 'Array of menu entries. Each entry is one of: an action item `{label, onClick?, icon?, isDisabled?, variant?}` (variant `"destructive"` renders it in the error color), a divider `{type: "divider"}`, or a section `{type: "section", title?, items: [...action items]}`.',
       required: true,
     },
     {
@@ -95,7 +95,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description: '右键点击时在光标位置出现的上下文菜单。用于为特定元素或区域提供上下文操作，而不使 UI 杂乱。',
@@ -109,7 +109,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'right-click context menu at cursor position',
   usage: {

package/src/ContextMenu/ContextMenu.test.tsx

@@ -136,6 +136,21 @@ describe('ContextMenu', () => {
     expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled();
   });
 
+  it('closes the menu when Tab is pressed inside it (APG menu pattern)', () => {
+    render(
+      <ContextMenu items={[{label: 'Item 1'}]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    fireEvent.keyDown(menu, {key: 'Tab'});
+    expect(HTMLElement.prototype.hidePopover).toHaveBeenCalled();
+  });
+
   it('ignores Escape during IME composition', () => {
     render(
       <ContextMenu items={[{label: 'Item 1'}]}>
@@ -333,6 +348,27 @@ describe('ContextMenu items', () => {
   });
 });
 
+describe('ContextMenu destructive variant', () => {
+  it('forwards a destructive item variant to the shared menu item', () => {
+    render(
+      <ContextMenu
+        items={[
+          {label: 'Delete', variant: 'destructive', onClick: () => {}},
+          {label: 'Rename', onClick: () => {}},
+        ]}>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    expect(
+      screen.getByRole('menuitem', {name: 'Delete', hidden: true}),
+    ).toHaveAttribute('data-variant', 'destructive');
+    expect(
+      screen.getByRole('menuitem', {name: 'Rename', hidden: true}),
+    ).not.toHaveAttribute('data-variant');
+  });
+});
+
 describe('ContextMenu sections', () => {
   it('renders section with title', () => {
     render(
@@ -552,7 +588,7 @@ describe('ContextMenu selectable items', () => {
             <ContextMenuRadioGroup
               value="name"
               onChange={() => {}}
-              aria-label="Sort by">
+              label="Sort by">
               <ContextMenuRadioItem value="name" label="Sort by name" />
               <ContextMenuRadioItem value="date" label="Sort by date" />
             </ContextMenuRadioGroup>
@@ -587,7 +623,7 @@ describe('ContextMenu selectable items', () => {
             <ContextMenuRadioGroup
               value="name"
               onChange={onSort}
-              aria-label="Sort by">
+              label="Sort by">
               <ContextMenuRadioItem value="name" label="Sort by name" />
               <ContextMenuRadioItem value="date" label="Sort by date" />
             </ContextMenuRadioGroup>

package/src/ContextMenu/ContextMenu.tsx

@@ -27,7 +27,7 @@
  * - /packages/core/src/ContextMenu/ContextMenu.test.tsx
  * - /packages/core/src/ContextMenu/index.ts
  * - /apps/storybook/stories/ContextMenu.stories.tsx
- * - /packages/cli/templates/blocks/components/ContextMenu/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/ContextMenu/ (showcase blocks)
  */
 
 import React, {
@@ -220,12 +220,23 @@ export function ContextMenu({
   xstyle,
   triggerXstyle,
   'data-testid': testId,
-  ...props
+  ...rest
 }: ContextMenuProps) {
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.contextMenu.label');
-  const items = ('items' in props ? props.items : undefined) ?? [];
-  const menuContent = 'menuContent' in props ? props.menuContent : undefined;
+  // Separate content props (union discriminant) from DOM pass-through attrs.
+  // The union means exactly one of items/menuContent exists in rest; destructure
+  // both so triggerProps contains only DOM-safe attributes.
+  const {
+    items: itemsProp,
+    menuContent: menuContentProp,
+    ...triggerProps
+  } = rest as {items?: ContextMenuOption[]; menuContent?: ReactNode} & Omit<
+    typeof rest,
+    'items' | 'menuContent'
+  >;
+  const items = itemsProp ?? [];
+  const menuContent = menuContentProp;
 
   const menuId = useId();
   // Cursor point in the trigger's local coordinate space (offset from the
@@ -353,13 +364,22 @@ export function ContextMenu({
         }
         return;
       }
+      // APG menu pattern: Tab closes the menu. Menu items are tabIndex={-1}
+      // so Tab would otherwise leak focus into the page while the menu stayed
+      // open (menus-5). Do NOT preventDefault — closing restores focus to the
+      // previously focused element, and the browser's default Tab then
+      // continues from there to the next element.
+      if (e.key === 'Tab') {
+        closeMenu();
+        return;
+      }
       if (typeahead.onKeyDown(e)) {
         e.preventDefault();
         return;
       }
       listNavKeyDown(e);
     },
-    [listNavKeyDown, typeahead, ownsEvent],
+    [listNavKeyDown, closeMenu, typeahead, ownsEvent],
   );
 
   // Place the zero-size cursor anchor at a point in the trigger's local
@@ -440,7 +460,7 @@ export function ContextMenu({
   );
 
   const resolvedMenuContent =
-    props.items !== undefined ? renderDropdownItems(items) : menuContent;
+    itemsProp !== undefined ? renderDropdownItems(items) : menuContent;
 
   return (
     <>
@@ -448,6 +468,7 @@ export function ContextMenu({
         ref={mergeRefs(ref, triggerRef)}
         onContextMenu={handleContextMenu}
         {...longPressHandlers}
+        {...triggerProps}
         data-testid={testId}
         {...stylex.props(
           styles.trigger,

package/src/ContextMenu/ContextMenuItem.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: 'ContextMenuItem',