@astryxdesign/core 0.4.2 → 0.4.3-canary.551a8de

package/src/ComplexSelector/ComplexSelector.test.tsx

@@ -2,17 +2,45 @@
 
 /**
  * @file ComplexSelector.test.tsx
- * @input Uses vitest, Testing Library, user-event
- * @output Unit tests for ComplexSelector
- * @position Tests; validates custom content, async actions, and dialog composition
+ * @input Uses vitest, Testing Library, user-event, and ComplexSelector
+ * @output Unit tests for selection, trigger variants, positioning, and the imperative handle
+ * @position Tests; validates the ComplexSelector public interaction contract
  *
  * SYNC: When ComplexSelector.tsx API changes, update these tests.
  */
 
-import {describe, expect, it, vi} from 'vitest';
-import {render, screen, waitFor} from '@testing-library/react';
+import React from 'react';
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+import {act, fireEvent, render, screen, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {ComplexSelector} from './ComplexSelector';
+import {ComplexSelector, type ComplexSelectorHandle} from './ComplexSelector';
+
+const originalMatches = HTMLElement.prototype.matches;
+
+// Mock the Popover API, which jsdom does not implement.
+beforeEach(() => {
+  HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+    this.setAttribute('popover-open', '');
+    const event = new Event('toggle');
+    Object.defineProperty(event, 'newState', {value: 'open'});
+    this.dispatchEvent(event);
+  });
+  HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+    this.removeAttribute('popover-open');
+    const event = new Event('toggle');
+    Object.defineProperty(event, 'newState', {value: 'closed'});
+    this.dispatchEvent(event);
+  });
+  Object.defineProperty(HTMLElement.prototype, 'matches', {
+    configurable: true,
+    value: function (this: HTMLElement, selector: string): boolean {
+      if (selector === ':popover-open') {
+        return this.hasAttribute('popover-open');
+      }
+      return originalMatches.call(this, selector);
+    },
+  });
+});
 
 type FruitValue = {
   fruit: 'Apple' | 'Banana';
@@ -83,6 +111,35 @@ function FruitComplexSelector({
 }
 
 describe('ComplexSelector', () => {
+  it('defaults to md and reflects explicit trigger sizes', () => {
+    const {container, rerender} = render(
+      <ComplexSelector label="Fruit blend" value="Apple">
+        {() => <div>Options</div>}
+      </ComplexSelector>,
+    );
+
+    const getSelector = () =>
+      container.querySelector('.astryx-complex-selector');
+
+    expect(getSelector()).toHaveAttribute('data-size', 'md');
+
+    rerender(
+      <ComplexSelector label="Fruit blend" value="Apple" size="sm">
+        {() => <div>Options</div>}
+      </ComplexSelector>,
+    );
+
+    expect(getSelector()).toHaveAttribute('data-size', 'sm');
+
+    rerender(
+      <ComplexSelector label="Fruit blend" value="Apple" size="lg">
+        {() => <div>Options</div>}
+      </ComplexSelector>,
+    );
+
+    expect(getSelector()).toHaveAttribute('data-size', 'lg');
+  });
+
   it('renders custom content with value and commits through onChange', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();
@@ -174,6 +231,140 @@ describe('ComplexSelector', () => {
     await user.click(screen.getByRole('button', {name: 'Done', ...h}));
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
   });
+
+  it('renders a ghost toolbar trigger with a start icon', () => {
+    const {container} = render(
+      <ComplexSelector
+        label="View options"
+        value={['name']}
+        variant="ghost"
+        startIcon="viewColumns"
+        status={{type: 'warning', message: 'Unsaved changes'}}
+        data-testid="view-options">
+        {() => <div>Columns</div>}
+      </ComplexSelector>,
+    );
+
+    expect(container.querySelector('.astryx-complex-selector')).toHaveAttribute(
+      'data-variant',
+      'ghost',
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+    expect(
+      screen.getByTestId('view-options').querySelectorAll('svg'),
+    ).toHaveLength(2);
+  });
+
+  it('supports end-aligned popup positioning', () => {
+    render(
+      <ComplexSelector label="View options" value={[]} alignment="end">
+        {() => <div>Columns</div>}
+      </ComplexSelector>,
+    );
+
+    const popover = screen
+      .getByRole('dialog', {hidden: true})
+      .closest('[popover]');
+    expect(popover?.getAttribute('style')).toContain(
+      'position-area: self-block-end span-self-inline-start',
+    );
+  });
+
+  it('exposes imperative open, close, toggle, and isOpen via handleRef', async () => {
+    const handleRef = React.createRef<ComplexSelectorHandle>();
+    render(
+      <ComplexSelector label="View options" value={[]} handleRef={handleRef}>
+        {() => <button type="button">Apply</button>}
+      </ComplexSelector>,
+    );
+    const trigger = screen.getByRole('button', {name: 'View options'});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(handleRef.current?.isOpen()).toBe(false);
+
+    act(() => {
+      handleRef.current?.open();
+    });
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    });
+    expect(handleRef.current?.isOpen()).toBe(true);
+
+    act(() => {
+      handleRef.current?.close();
+    });
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+    expect(handleRef.current?.isOpen()).toBe(false);
+
+    act(() => {
+      handleRef.current?.toggle();
+    });
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+    });
+
+    act(() => {
+      handleRef.current?.toggle();
+    });
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    });
+  });
+
+  it('does not open via the imperative handle when disabled', async () => {
+    const handleRef = React.createRef<ComplexSelectorHandle>();
+    render(
+      <ComplexSelector
+        label="View options"
+        value={[]}
+        isDisabled
+        handleRef={handleRef}>
+        {() => <button type="button">Apply</button>}
+      </ComplexSelector>,
+    );
+    const trigger = screen.getByRole('button', {name: 'View options'});
+
+    act(() => {
+      handleRef.current?.open();
+    });
+    act(() => {
+      handleRef.current?.toggle();
+    });
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(handleRef.current?.isOpen()).toBe(false);
+  });
+
+  it('does not reopen from the trigger click that follows light dismiss', async () => {
+    const user = userEvent.setup();
+    render(
+      <ComplexSelector label="View options" value={[]}>
+        {() => <button type="button">Apply</button>}
+      </ComplexSelector>,
+    );
+    const trigger = screen.getByRole('button', {name: 'View options'});
+
+    await user.click(trigger);
+    const popover = screen
+      .getByRole('dialog', {hidden: true})
+      .closest('[popover]');
+    expect(popover).not.toBeNull();
+
+    const closeEvent = new Event('toggle');
+    Object.defineProperty(closeEvent, 'newState', {value: 'closed'});
+    fireEvent(popover as HTMLElement, closeEvent);
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+    const showCallCount = vi.mocked(HTMLElement.prototype.showPopover).mock
+      .calls.length;
+    fireEvent.click(trigger);
+    expect(HTMLElement.prototype.showPopover).toHaveBeenCalledTimes(
+      showCallCount,
+    );
+  });
 });
 
 describe('ComplexSelector popup theme target', () => {

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/Markdown/parser.test.ts

@@ -51,6 +51,48 @@ describe('parseInline', () => {
     expect(result).toEqual([{type: 'image', src: 'img.png', alt: 'alt'}]);
   });
 
+  it('rejects javascript: links as plain text (XSS prevention)', () => {
+    const result = parseInline('[click](javascript:alert(1))');
+    // Should be emitted as plain text, NOT as a link node
+    expect(result).toEqual([
+      {type: 'text', content: '[click](javascript:alert(1))'},
+    ]);
+  });
+
+  it('rejects javascript: with mixed case and whitespace (XSS prevention)', () => {
+    const result = parseInline('[click](JaVaScRiPt:alert(1))');
+    expect(result).toEqual([
+      {type: 'text', content: '[click](JaVaScRiPt:alert(1))'},
+    ]);
+  });
+
+  it('rejects vbscript: links (XSS prevention)', () => {
+    const result = parseInline('[click](vbscript:MsgBox(1))');
+    expect(result).toEqual([
+      {type: 'text', content: '[click](vbscript:MsgBox(1))'},
+    ]);
+  });
+
+  it('rejects data:text/html image src (XSS prevention)', () => {
+    const result = parseInline(
+      '![xss](data:text/html,<script>alert(1)</script>)',
+    );
+    expect(result).toEqual([
+      {
+        type: 'text',
+        content: '![xss](data:text/html,<script>alert(1)</script>)',
+      },
+    ]);
+  });
+
+  it('allows normal http/https links', () => {
+    const result = parseInline('[safe](https://example.com)');
+    expect(result[0].type).toBe('link');
+    if (result[0].type === 'link') {
+      expect(result[0].href).toBe('https://example.com');
+    }
+  });
+
   it('parses strikethrough', () => {
     const result = parseInline('~~deleted~~');
     expect(result[0].type).toBe('strikethrough');
@@ -727,6 +769,17 @@ describe('citation parsing', () => {
       });
     });
 
+    it('rejects <javascript:...> angle-bracket autolinks (XSS prevention)', () => {
+      const result = parseInline('see <javascript:alert(1)> ok', {
+        autolink: 'gfm',
+      });
+      // Should NOT produce a link node with javascript: href
+      const linkNodes = result.filter(
+        (n): n is Extract<typeof n, {type: 'link'}> => n.type === 'link',
+      );
+      expect(linkNodes).toHaveLength(0);
+    });
+
     it('parses <email> angle-bracket autolinks', () => {
       const result = parseInline('mail <user@example.com> please', {
         autolink: 'gfm',