@astryxdesign/core 0.4.2 → 0.4.3-canary.00bed29

package/src/ComplexSelector/ComplexSelector.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file ComplexSelector.tsx
- * @input Uses React, StyleX, Field, usePopover
- * @output Exports ComplexSelector component for custom selector surfaces
+ * @input Uses React, StyleX, Field, Icon slots, Layer positioning, and usePopover
+ * @output Exports a rich-selector shell with exact token-sized input and ghost triggers, plus an imperative open/close handle
  * @position Core implementation; consumed by index.ts
  *
  * SYNC: When modified, update:
@@ -13,12 +13,15 @@
  * - /packages/core/src/ComplexSelector/ComplexSelector.test.tsx
  * - /packages/core/src/ComplexSelector/index.ts
  * - /apps/storybook/stories/ComplexSelector.stories.tsx
+ * - /packages/cli/assets/templates/blocks/components/ComplexSelector/ (showcase blocks)
  */
 
 import React, {
   useCallback,
   useId,
+  useImperativeHandle,
   useOptimistic,
+  useRef,
   useTransition,
   type ReactNode,
 } from 'react';
@@ -26,22 +29,24 @@ 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 {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
 import {useTranslator} from '../i18n';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
+import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {usePopover} from '../Popover/usePopover';
 import {
   colorVars,
   durationVars,
   easeVars,
+  fontWeightVars,
   radiusVars,
   sizeVars,
   spacingVars,
   typographyVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import type {SizeValue} from '../utils/types';
@@ -99,6 +104,39 @@ const styles = stylex.create({
   placeholder: {
     color: colorVars['--color-text-secondary'],
   },
+  triggerGhost: {
+    width: 'auto',
+    borderWidth: 0,
+    backgroundColor: 'transparent',
+    backgroundImage: {
+      default: null,
+      ':hover': {
+        '@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',
+      },
+      ':focus-within': 'none',
+    },
+    fontWeight: fontWeightVars['--font-weight-medium'],
+    transitionProperty:
+      'background-image, background-color, color, opacity, transform',
+    transform: {
+      default: 'scale(1)',
+      ':active': 'scale(0.98)',
+    },
+  },
+  triggerGhostDisabled: {
+    backgroundImage: 'none',
+    transform: {
+      default: 'none',
+      ':active': 'none',
+    },
+  },
   // 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.
@@ -129,19 +167,21 @@ const styles = stylex.create({
     padding: spacingVars['--spacing-3'],
   },
   sm: {
-    minHeight: sizeVars['--size-element-sm'],
+    height: sizeVars['--size-element-sm'],
   },
   md: {
-    minHeight: sizeVars['--size-element-md'],
+    height: sizeVars['--size-element-md'],
   },
   lg: {
-    minHeight: sizeVars['--size-element-lg'],
+    height: sizeVars['--size-element-lg'],
   },
   disabled: {
     cursor: 'not-allowed',
   },
 });
 
+export type ComplexSelectorVariant = 'input' | 'ghost';
+
 export type ComplexSelectorSize = 'sm' | 'md' | 'lg';
 
 export interface ComplexSelectorRenderState {
@@ -155,6 +195,25 @@ export interface ComplexSelectorRenderState {
   contentId: string;
 }
 
+/**
+ * Imperative control surface for ComplexSelector, accessed via the `handleRef`
+ * prop. Methods drive the same popover machinery as the built-in trigger, so
+ * they respect focus restoration, light dismiss, and Escape. Prefer these
+ * callbacks over mirroring open state in the parent — the selector owns its
+ * visibility, and imperative calls avoid the focus-management pitfalls of
+ * syncing an external `isOpen` prop.
+ */
+export interface ComplexSelectorHandle {
+  /** Open the selector surface. No-op when disabled or already open. */
+  open(): void;
+  /** Close the selector surface. Restores focus to the trigger. */
+  close(): void;
+  /** Toggle the selector surface open or closed. */
+  toggle(): void;
+  /** Whether the selector surface is currently open. Reads live state. */
+  isOpen(): boolean;
+}
+
 export interface ComplexSelectorStatus {
   type: 'warning' | 'error' | 'success';
   message?: string;
@@ -203,10 +262,22 @@ export interface ComplexSelectorProps<Value> extends Omit<
   labelTooltip?: string;
   /** Trigger and field size. */
   size?: ComplexSelectorSize;
+  /** Visual trigger style. Ghost matches toolbar buttons. */
+  variant?: ComplexSelectorVariant;
+  /** Icon displayed at the start of the trigger. */
+  startIcon?: ReactNode | IconType;
   /** Width of the field. */
   width?: SizeValue;
   /** Popup placement. */
-  placement?: 'above' | 'below' | 'start' | 'end';
+  placement?: LayerPlacement;
+  /** Popup alignment along the placement axis. */
+  alignment?: LayerAlignment;
+  /**
+   * Imperative handle for programmatic open/close control. Exposes open,
+   * close, toggle, and the isOpen query. Use this instead of mirroring open
+   * state in the parent — the selector owns its visibility.
+   */
+  handleRef?: React.Ref<ComplexSelectorHandle>;
   /** StyleX styles for the popup content container. */
   contentXstyle?: StyleXStyles;
   /** Test ID for the trigger container. */
@@ -258,8 +329,12 @@ export function ComplexSelector<Value>({
   statusVariant = 'attached',
   labelTooltip,
   size = 'md',
+  variant = 'input',
+  startIcon,
   width,
   placement = 'below',
+  alignment = 'start',
+  handleRef,
   contentXstyle,
   xstyle,
   className,
@@ -270,6 +345,10 @@ export function ComplexSelector<Value>({
 }: ComplexSelectorProps<Value>) {
   const t = useTranslator();
   const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
+  const effectiveStatusVariant =
+    variant === 'ghost' && statusVariant === 'attached'
+      ? 'detached'
+      : statusVariant;
 
   const triggerId = useId();
   const labelId = useId();
@@ -284,24 +363,67 @@ export function ComplexSelector<Value>({
       .filter((id): id is string => id != null)
       .join(' ') || undefined;
 
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const lastHideTimeRef = useRef(0);
+
   const [isPending, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || isPending;
 
+  const handlePopoverHide = useCallback(() => {
+    lastHideTimeRef.current = Date.now();
+    triggerRef.current?.focus();
+  }, []);
+
   const popover = usePopover({
     dialogLabel: label,
     hasCloseButton: false,
     hasAutoFocus: true,
-    // The popup's theme target belongs on the SURFACE — the element painting
-    // background, radius and elevation — which `usePopover` owns. Rendered on
-    // the content box below it, a theme's background or radius rule paints the
-    // wrong box.
     surfaceTarget: 'complex-selector-popup',
-    onHide: () => {
-      document.getElementById(triggerId)?.focus();
-    },
+    onHide: handlePopoverHide,
   });
 
+  const isOpen = popover.isOpen;
+
+  const handleTriggerClick = useCallback(() => {
+    if (isDisabled || Date.now() - lastHideTimeRef.current < 50) {
+      return;
+    }
+    if (popover.isOpen) {
+      popover.hide();
+    } else {
+      popover.show();
+    }
+  }, [isDisabled, popover]);
+
+  const close = useCallback(() => {
+    popover.hide();
+  }, [popover]);
+
+  useImperativeHandle(
+    handleRef,
+    () => ({
+      open: () => {
+        if (!isDisabled) {
+          popover.show();
+        }
+      },
+      close: () => popover.hide(),
+      toggle: () => {
+        if (isDisabled) {
+          return;
+        }
+        if (popover.isOpen) {
+          popover.hide();
+        } else {
+          popover.show();
+        }
+      },
+      isOpen: () => popover.isOpen,
+    }),
+    [isDisabled, popover],
+  );
+
   const commitValue = useCallback(
     (nextValue: Value) => {
       onChange?.(nextValue);
@@ -317,10 +439,15 @@ export function ComplexSelector<Value>({
 
   const triggerContent = triggerLabel ?? placeholder;
 
+  const startIconSlot = renderIconSlot(startIcon, {
+    size: 'sm',
+    color: 'secondary',
+  });
+
   const content = (
     <div id={contentId} {...stylex.props(styles.content, contentXstyle)}>
-      {children(optimisticValue, commitValue, popover.hide, {
-        isOpen: popover.isOpen,
+      {children(optimisticValue, commitValue, close, {
+        isOpen,
         isBusy,
         triggerId,
         contentId,
@@ -334,13 +461,10 @@ export function ComplexSelector<Value>({
         ref={popover.triggerRef}
         data-testid={testId}
         {...props}
-        onClick={composeEventHandlers(onClickProp, () => {
-          if (!isDisabled) {
-            popover.toggle();
-          }
-        })}
+        onClick={composeEventHandlers(onClickProp, handleTriggerClick)}
         {...mergeProps(
           themeProps('complex-selector', {
+            variant,
             size,
             status: status?.type ?? null,
           }),
@@ -353,7 +477,9 @@ export function ComplexSelector<Value>({
             // matched a mouse click on the trigger and drew the outline for
             // pointer users too. `focusWithin` here is `:has(:focus-visible)`.
             focusOutlineStyles.focusWithin,
+            variant === 'ghost' && styles.triggerGhost,
             isDisabled && inputWrapperStyles.disabled,
+            variant === 'ghost' && isDisabled && styles.triggerGhostDisabled,
             isDisabled && styles.disabled,
             triggerLabel == null && styles.placeholder,
             xstyle,
@@ -361,11 +487,13 @@ export function ComplexSelector<Value>({
           className,
           style,
         )}>
+        {isRenderable(startIconSlot) && startIconSlot}
         <button
+          ref={triggerRef}
           id={triggerId}
           type="button"
           aria-haspopup="dialog"
-          aria-expanded={popover.isOpen}
+          aria-expanded={isOpen}
           aria-controls={contentId}
           aria-describedby={ariaDescribedBy}
           aria-labelledby={labelId}
@@ -374,7 +502,7 @@ export function ComplexSelector<Value>({
           aria-busy={isBusy || undefined}
           disabled={isDisabled}
           onKeyDown={event => {
-            if (event.key === 'ArrowDown' && !popover.isOpen && !isDisabled) {
+            if (event.key === 'ArrowDown' && !isOpen && !isDisabled) {
               event.preventDefault();
               popover.show();
             }
@@ -394,17 +522,17 @@ export function ComplexSelector<Value>({
           xstyle={[
             styles.triggerIcon,
             styles.triggerIconRotation,
-            popover.isOpen && styles.triggerIconOpen,
+            isOpen && styles.triggerIconOpen,
           ]}
           {...themeProps('complex-selector-indicator-icon', {
-            state: popover.isOpen ? 'expanded' : 'collapsed',
+            state: isOpen ? 'expanded' : 'collapsed',
           })}
         />
       </div>
 
       {popover.render(content, {
         placement,
-        alignment: 'start',
+        alignment,
         offset: spacingVars['--spacing-1'],
         xstyle: [styles.popover, layerAnimations[placement]],
       })}
@@ -431,7 +559,7 @@ export function ComplexSelector<Value>({
             }
           : undefined
       }
-      statusVariant={statusVariant}
+      statusVariant={effectiveStatusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {selectorContent}

package/src/ComplexSelector/index.ts

@@ -4,14 +4,16 @@
 
 /**
  * @file index.ts
- * @output Exports ComplexSelector and types
+ * @output Exports ComplexSelector and its trigger-size contract types
  * @position Public API entry point
  */
 
 export {
   ComplexSelector,
+  type ComplexSelectorHandle,
   type ComplexSelectorProps,
   type ComplexSelectorRenderState,
   type ComplexSelectorSize,
   type ComplexSelectorStatus,
+  type ComplexSelectorVariant,
 } from './ComplexSelector';

package/src/ContextMenu/ContextMenu.tsx

@@ -63,7 +63,7 @@ import {
   easeVars,
   shadowVars,
 } from '../theme/tokens.stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps, mergeRefs, isImeKeyEvent} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {StyleXStyles} from '../theme/types';
 import {themeProps} from '../utils/themeProps';
@@ -334,7 +334,9 @@ export function ContextMenu({
       if (e.key !== 'Escape') {
         return;
       }
-      if (e.isComposing || e.keyCode === 229) {
+      if (isImeKeyEvent(e)) {
+        // Ignore Escape that is committing/cancelling an IME composition;
+        // see utils/ime.ts for why.
         return;
       }
       e.preventDefault();

package/src/DateInput/DateInput.test.tsx

@@ -536,6 +536,27 @@ describe('DateInput', () => {
     expect(onChange).toHaveBeenCalledWith('2026-03-15');
   });
 
+  it('does not commit on a composing Enter (IME)', () => {
+    const onChange = vi.fn();
+    render(<DateInput label="Date" onChange={onChange} />);
+
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: '03/15/2026'}});
+    onChange.mockClear();
+
+    // The composing keydown (isComposing / legacy keyCode 229) that commits an
+    // IME candidate fires before compositionend; it must not be read as
+    // "commit the typed date".
+    fireEvent.keyDown(input, {key: 'Enter', isComposing: true});
+    expect(onChange).not.toHaveBeenCalled();
+    fireEvent.keyDown(input, {key: 'Enter', keyCode: 229});
+    expect(onChange).not.toHaveBeenCalled();
+
+    // A real, non-composing Enter still commits.
+    fireEvent.keyDown(input, {key: 'Enter'});
+    expect(onChange).toHaveBeenCalledWith('2026-03-15');
+  });
+
   // --- Arrow-down opens calendar popover ---
 
   // Note: Tests involving popover rendering (show/hide with calendar)

package/src/DateInput/DateInput.tsx

@@ -60,7 +60,7 @@ import {useCalendarConstraints} from '../Calendar/hooks';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {usePopover} from '../Popover';
 import {useTooltip} from '../Tooltip';
-import {getInputARIA, parseDateInput} from '../utils';
+import {getInputARIA, isImeKeyEvent, parseDateInput} from '../utils';
 import {
   plainDateFromISO,
   plainDateToISO,
@@ -627,6 +627,14 @@ export function DateInput({
   // Handle keyboard events on input
   const handleInputKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
+      // An in-progress IME composition uses Enter to commit the candidate and
+      // Escape to cancel it; that composing keydown fires before
+      // compositionend, so without this guard a Korean/Japanese/Chinese user
+      // committing a syllable with Enter would instead commit the pending date
+      // (or Escape would close the calendar mid-composition). See utils/ime.ts.
+      if (isImeKeyEvent(e.nativeEvent)) {
+        return;
+      }
       if (e.key === 'Escape' && popover.isOpen) {
         e.preventDefault();
         popover.hide();

package/src/DateTimeInput/DateTimeInput.doc.mjs

@@ -204,6 +204,8 @@ export const docs = {
         className: 'astryx-date-time-input-time-segment',
         visualProps: ['size', 'status'],
       },
+      {className: 'astryx-date-time-input-toggle-icon', states: ['state']},
+      {className: 'astryx-date-time-input-clock-icon'},
     ],
   },
   usage: {
@@ -508,6 +510,8 @@ export const docsZh = {
         className: 'astryx-date-time-input-time-segment',
         visualProps: ['size', 'status'],
       },
+      {className: 'astryx-date-time-input-toggle-icon', states: ['state']},
+      {className: 'astryx-date-time-input-clock-icon'},
     ],
   },
 };

package/src/DateTimeInput/DateTimeInput.test.tsx

@@ -15,6 +15,7 @@ import userEvent from '@testing-library/user-event';
 import {getButton, queryButton} from '../__tests__/fastRoleQueries';
 import {DateTimeInput} from './DateTimeInput';
 import type {ISODateTimeString} from './DateTimeInput';
+import {Icon} from '../Icon';
 import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
 import {InternationalizationProvider} from '../i18n';
@@ -96,6 +97,48 @@ describe('DateTimeInput', () => {
     expect(screen.getByLabelText('Meeting time')).toBeInTheDocument();
   });
 
+  it('does not commit the date on a composing Enter (IME)', () => {
+    const onChange = vi.fn();
+    render(<DateTimeInput label="Meeting" onChange={onChange} />);
+    const dateInput = screen.getByRole('combobox');
+    fireEvent.change(dateInput, {target: {value: '03/15/2026'}});
+    onChange.mockClear();
+
+    // The composing keydown (isComposing / legacy keyCode 229) that commits an
+    // IME candidate must not be read as "commit the typed date".
+    fireEvent.keyDown(dateInput, {key: 'Enter', isComposing: true});
+    expect(onChange).not.toHaveBeenCalled();
+    fireEvent.keyDown(dateInput, {key: 'Enter', keyCode: 229});
+    expect(onChange).not.toHaveBeenCalled();
+
+    // A real, non-composing Enter still commits.
+    fireEvent.keyDown(dateInput, {key: 'Enter'});
+    expect(onChange).toHaveBeenCalled();
+  });
+
+  it('does not step the time on a composing ArrowUp (IME)', () => {
+    const onChange = vi.fn();
+    render(
+      <DateTimeInput
+        label="Meeting"
+        value={'2026-03-15T14:30' as ISODateTimeString}
+        onChange={onChange}
+      />,
+    );
+    const timeInput = screen.getByLabelText('Meeting time');
+
+    // An IME candidate window navigates with the arrows; a composing ArrowUp
+    // must not step the time value.
+    fireEvent.keyDown(timeInput, {key: 'ArrowUp', isComposing: true});
+    expect(onChange).not.toHaveBeenCalled();
+    fireEvent.keyDown(timeInput, {key: 'ArrowUp', keyCode: 229});
+    expect(onChange).not.toHaveBeenCalled();
+
+    // A real, non-composing ArrowUp still steps the time by one minute.
+    fireEvent.keyDown(timeInput, {key: 'ArrowUp'});
+    expect(onChange).toHaveBeenCalledWith('2026-03-15T14:31');
+  });
+
   it('displays formatted date in date input when value is provided', () => {
     render(
       <DateTimeInput
@@ -1063,6 +1106,100 @@ describe('DateTimeInput', () => {
       expect(css).toContain('block-size: var(--size-element-lg)');
       expect(css).toContain('padding-inline: var(--spacing-4)');
     });
+
+    it('renders the toggle-icon target on the calendar glyph with open/closed state', async () => {
+      const {container} = render(
+        <DateTimeInput label="Meeting" onChange={() => {}} />,
+      );
+      // The stable target lands on the icon element itself (not the button),
+      // so a theme can restyle just this glyph — mirroring
+      // `date-input-toggle-icon`.
+      const icon = container.querySelector(
+        '.astryx-date-time-input-toggle-icon',
+      );
+      expect(icon).not.toBeNull();
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveAttribute('data-state', 'collapsed');
+
+      fireEvent.click(getButton('Open calendar'));
+      await waitFor(() => {
+        expect(
+          container.querySelector('.astryx-date-time-input-toggle-icon'),
+        ).toHaveAttribute('data-state', 'expanded');
+      });
+    });
+
+    it('renders the clock-icon target on the leading time glyph', () => {
+      const {container} = render(
+        <DateTimeInput label="Meeting" onChange={() => {}} />,
+      );
+      const icon = container.querySelector(
+        '.astryx-date-time-input-clock-icon',
+      );
+      expect(icon).not.toBeNull();
+      expect(icon).toHaveClass('astryx-icon');
+    });
+
+    it('leaves both leading glyphs byte-identical to a plain secondary/sm icon by default', () => {
+      // The targets are purely additive: the stable target class and its
+      // reflected state add nothing to the render until a theme targets them.
+      // Guard that by diffing each glyph's StyleX classes against a standalone
+      // secondary/sm icon, excluding only the additive target/state classes.
+      const {container} = render(
+        <DateTimeInput label="Meeting" onChange={() => {}} />,
+      );
+      const calendarIcon = container.querySelector(
+        '.astryx-date-time-input-toggle-icon',
+      ) as HTMLElement;
+      const clockIcon = container.querySelector(
+        '.astryx-date-time-input-clock-icon',
+      ) as HTMLElement;
+
+      const {container: refContainer} = render(
+        <Icon icon="calendar" size="sm" color="secondary" />,
+      );
+      const refIcon = refContainer.querySelector('.astryx-icon') as HTMLElement;
+
+      const themeTargetClasses = new Set([
+        'astryx-date-time-input-toggle-icon',
+        'astryx-date-time-input-clock-icon',
+        'collapsed',
+        'expanded',
+      ]);
+      const styleClasses = (el: HTMLElement) =>
+        el.className
+          .split(' ')
+          .filter(c => !themeTargetClasses.has(c))
+          .sort();
+
+      expect(styleClasses(calendarIcon)).toEqual(styleClasses(refIcon));
+      expect(styleClasses(clockIcon)).toEqual(styleClasses(refIcon));
+    });
+
+    it('exposes the icon targets so a theme reaches their size and per-state color', () => {
+      // jsdom cannot resolve the @layer cascade, so the generated CSS is what
+      // proves a same-element theme rule can reach these glyphs and win over
+      // the icon's own base size/color.
+      const theme = defineTheme({
+        name: 'date-time-input-icon-targets-test',
+        components: {
+          'date-time-input-toggle-icon': {
+            base: {width: '14px', height: '14px', fontSize: '14px'},
+            'state:expanded': {color: 'var(--color-icon-primary)'},
+          },
+          'date-time-input-clock-icon': {
+            base: {width: '14px', height: '14px', fontSize: '14px'},
+          },
+        },
+      });
+      const css = generateThemeTestCSS(theme);
+
+      expect(css).toContain('.astryx-date-time-input-toggle-icon {');
+      expect(css).toContain('.astryx-date-time-input-toggle-icon.expanded');
+      expect(css).toContain('.astryx-date-time-input-clock-icon {');
+      expect(css).toContain('width: 14px');
+      expect(css).toContain('color: var(--color-icon-primary)');
+    });
   });
 });