@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Toast/ToastViewport.tsx

@@ -2,6 +2,18 @@
 
 'use client';
 
+/**
+ * @file ToastViewport.tsx
+ * @input Uses React state/effects, ToastContext, useAnnounce, viewport tokens,
+ *   and placement-derived motion variables
+ * @output Exports the ToastViewport provider, stack, live announcement dispatch,
+ *   focus handoff, safe-area-aware edge gutters, and motion context
+ * @position Core provider/imperative viewport for useToast()
+ *
+ * SYNC: When placement, stacking, focus, announcement, or safe-area behavior
+ *   changes, update ToastViewport.test.tsx, Toast.doc.mjs, and Toast.stories.tsx.
+ */
+
 import {
   isValidElement,
   useCallback,
@@ -22,13 +34,30 @@ import {ToastContext, type ToastContextValue} from './ToastContext';
 import type {ToastEntry, ToastPosition, ToastDismissReason} from './types';
 import {useTranslator} from '../i18n';
 
+const SAFE_AREA_INLINE_START = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px))`;
+const SAFE_AREA_INLINE_END = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px))`;
+const SAFE_AREA_BLOCK_START = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-top, 0px))`;
+const SAFE_AREA_BLOCK_END = `max(${spacingVars['--spacing-4']}, env(safe-area-inset-bottom, 0px))`;
+const TOAST_EDGE_DRIFT = spacingVars['--spacing-2'];
+const TOAST_EDGE_DRIFT_NEGATIVE = `calc(-1 * ${TOAST_EDGE_DRIFT})`;
+
 const styles = stylex.create({
   viewport: {
     position: 'fixed',
     zIndex: 500,
     display: 'flex',
+    boxSizing: 'border-box',
     flexDirection: 'column',
-    padding: spacingVars['--spacing-4'],
+    paddingBlockStart: SAFE_AREA_BLOCK_START,
+    paddingBlockEnd: SAFE_AREA_BLOCK_END,
+    paddingInlineStart: {
+      default: SAFE_AREA_INLINE_START,
+      ':is([dir="rtl"] *)': SAFE_AREA_INLINE_END,
+    },
+    paddingInlineEnd: {
+      default: SAFE_AREA_INLINE_END,
+      ':is([dir="rtl"] *)': SAFE_AREA_INLINE_START,
+    },
     pointerEvents: 'none',
     // Reset popover styles — the popover attribute puts us in the top
     // layer (above dialogs), but we don't want its default styles.
@@ -40,25 +69,29 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     overflow: 'visible',
   },
-  bottomEnd: {bottom: 0, insetInlineEnd: 0, alignItems: 'flex-end'},
-  bottomStart: {bottom: 0, insetInlineStart: 0, alignItems: 'flex-start'},
+  viewportInlineSpan: {
+    insetInlineStart: 0,
+    insetInlineEnd: 0,
+  },
+  bottomEnd: {bottom: 0, alignItems: 'flex-end'},
+  bottomStart: {bottom: 0, alignItems: 'flex-start'},
   topEnd: {
     top: 0,
-    insetInlineEnd: 0,
     alignItems: 'flex-end',
     flexDirection: 'column-reverse',
   },
   topStart: {
     top: 0,
-    insetInlineStart: 0,
     alignItems: 'flex-start',
     flexDirection: 'column-reverse',
   },
   toastWrapper: {
     pointerEvents: 'auto',
     display: 'grid',
+    width: '100%',
+    maxWidth: 400,
+    minWidth: 0,
     gridTemplateRows: '1fr',
-    paddingBlockEnd: spacingVars['--spacing-3'],
     transitionProperty: 'grid-template-rows, padding',
     transitionDuration: {
       default: durationVars['--duration-fast'],
@@ -70,11 +103,33 @@ const styles = stylex.create({
       paddingBlockEnd: 0,
     },
   },
+  toastWrapperFromBottom: {
+    '--_toast-slide-y': TOAST_EDGE_DRIFT,
+  },
+  toastWrapperFromTop: {
+    '--_toast-slide-y': TOAST_EDGE_DRIFT_NEGATIVE,
+  },
+  // The inter-toast gap is padding on each wrapper so it collapses with the
+  // grid track. The wrapper nearest the viewport edge drops that padding; the
+  // child flips because top stacks use column-reverse.
+  toastWrapperGap: {
+    paddingBlockEnd: {default: spacingVars['--spacing-2'], ':last-child': 0},
+  },
+  toastWrapperGapReversed: {
+    paddingBlockEnd: {default: spacingVars['--spacing-2'], ':first-child': 0},
+  },
   toastWrapperExiting: {
     gridTemplateRows: '0fr',
     paddingBlockEnd: 0,
   },
   toastWrapperInner: {
+    width: '100%',
+    maxWidth: '100%',
+    minWidth: 0,
+    minHeight: 0,
+    // Required for the 1fr -> 0fr exit collapse to hide the shrinking Toast.
+    // This preserves main's paint containment; browser-chrome behavior is not
+    // changed or claimed by this responsive-layout fix.
     overflow: 'hidden',
   },
 });
@@ -104,6 +159,7 @@ function getNodeText(node: ReactNode): string {
 
 export interface ToastViewportProps {
   position?: ToastPosition;
+  /** Maximum number of visible toasts. @default 5 */
   maxVisible?: number;
   inset?: {top?: number; bottom?: number; start?: number; end?: number};
   /**
@@ -341,6 +397,7 @@ export function ToastViewport({
   );
 
   const visibleToasts = toasts.slice(-maxVisible);
+
   const insetStyle: React.CSSProperties = {};
   if (inset?.top) {
     insetStyle.top = inset.top;
@@ -417,21 +474,31 @@ export function ToastViewport({
         : position === 'bottomStart'
           ? styles.bottomStart
           : styles.bottomEnd;
+  const isReversed = position === 'topEnd' || position === 'topStart';
+  const toastWrapperPositionStyle = isReversed
+    ? styles.toastWrapperFromTop
+    : styles.toastWrapperFromBottom;
+  const gapStyle = isReversed
+    ? styles.toastWrapperGapReversed
+    : styles.toastWrapperGap;
 
   return (
     <ToastContext value={contextValue}>
       {children}
       <div
         ref={viewportRef}
-        role="region"
-        aria-label={t('@astryx.toast.viewport')}
-        tabIndex={-1}
+        role={hasToasts ? 'region' : undefined}
+        aria-label={hasToasts ? t('@astryx.toast.viewport') : undefined}
+        tabIndex={hasToasts ? -1 : undefined}
         // popover="manual" promotes to the top layer (above dialogs).
         // Omitted inside dialogs where the viewport is already in a top layer.
         popover={isTopLayer ? 'manual' : undefined}
-        {...mergeProps(stylex.props(styles.viewport, posStyle), {
-          style: Object.keys(insetStyle).length > 0 ? insetStyle : undefined,
-        })}>
+        {...mergeProps(
+          stylex.props(styles.viewport, styles.viewportInlineSpan, posStyle),
+          {
+            style: Object.keys(insetStyle).length > 0 ? insetStyle : undefined,
+          },
+        )}>
         {visibleToasts.map(entry => {
           const o = entry.options;
           const type = o.type ?? 'info';
@@ -444,6 +511,8 @@ export function ToastViewport({
               data-toast-id={entry.id}
               {...stylex.props(
                 styles.toastWrapper,
+                toastWrapperPositionStyle,
+                gapStyle,
                 isExiting && styles.toastWrapperExiting,
               )}
               onTransitionEnd={

package/src/Token/Token.test.tsx

@@ -521,3 +521,98 @@ describe('Token focus outline', () => {
     expect(container.tagName).toBe('SPAN');
   });
 });
+
+describe('Token pass-through props', () => {
+  it('forwards pass-through props to the token element', () => {
+    render(
+      <Token
+        label="Design"
+        aria-label="Design tag"
+        id="design-token"
+        data-source="filters"
+        data-testid="token"
+      />,
+    );
+    const token = screen.getByTestId('token');
+    expect(token).toHaveAttribute('aria-label', 'Design tag');
+    expect(token).toHaveAttribute('id', 'design-token');
+    expect(token).toHaveAttribute('data-source', 'filters');
+  });
+
+  it('forwards pass-through props on the clickable and link variants', () => {
+    const {rerender} = render(
+      <Token
+        label="Design"
+        onClick={() => {}}
+        id="clickable"
+        data-testid="token"
+      />,
+    );
+    expect(screen.getByTestId('token')).toHaveAttribute('id', 'clickable');
+
+    rerender(
+      <Token label="Design" href="/tags" id="link" data-testid="token" />,
+    );
+    expect(screen.getByTestId('token')).toHaveAttribute('id', 'link');
+  });
+
+  it('keeps its own label when the label is visually hidden', () => {
+    render(
+      <Token
+        label="Design"
+        isLabelHidden
+        aria-label="Caller label"
+        data-source="filters"
+        data-testid="token"
+      />,
+    );
+    const token = screen.getByTestId('token');
+    expect({
+      ariaLabel: token.getAttribute('aria-label'),
+      dataSource: token.getAttribute('data-source'),
+    }).toEqual({ariaLabel: 'Design', dataSource: 'filters'});
+  });
+});
+
+describe('Token — owned handlers on the link+remove container', () => {
+  it("composes a caller's onMouseUp with the container's link delegation", () => {
+    const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
+    const handleMouseUp = vi.fn();
+    render(
+      <Token
+        label="Tag"
+        href="/test"
+        onRemove={() => {}}
+        onMouseUp={handleMouseUp}
+        icon={<span data-testid="icon">★</span>}
+      />,
+    );
+
+    fireEvent.mouseUp(screen.getByTestId('icon'), {button: 1});
+
+    expect(handleMouseUp).toHaveBeenCalledOnce();
+    expect(openSpy).toHaveBeenCalledWith('/test', '_blank', 'noopener');
+    openSpy.mockRestore();
+  });
+
+  it("does not fire the container's delegation when disabled, but still forwards the caller's onMouseUp", () => {
+    const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
+    const handleMouseUp = vi.fn();
+    render(
+      <Token
+        label="Tag"
+        href="/test"
+        onRemove={() => {}}
+        onMouseUp={handleMouseUp}
+        isDisabled
+        icon={<span data-testid="icon">★</span>}
+      />,
+    );
+
+    fireEvent.mouseUp(screen.getByTestId('icon'), {button: 1});
+
+    expect(handleMouseUp).toHaveBeenCalledOnce();
+    expect(openSpy).not.toHaveBeenCalled();
+    openSpy.mockRestore();
+  });
+});

package/src/Token/Token.tsx

@@ -307,6 +307,7 @@ export function Token({
   style,
   'data-testid': testId,
   ref,
+  ...rest
 }: TokenProps) {
   const t = useTranslator();
   const LinkComponent = useLinkComponent();
@@ -344,8 +345,8 @@ export function Token({
 
   const sharedProps = {
     'data-testid': testId,
-    'aria-label': isLabelHidden ? label : undefined,
-    'aria-description': description,
+    ...(isLabelHidden ? {'aria-label': label} : {}),
+    ...(description != null ? {'aria-description': description} : {}),
   };
 
   if (role === 'link') {
@@ -354,8 +355,6 @@ export function Token({
         <LinkComponent
           ref={ref as React.Ref<HTMLAnchorElement>}
           href={href as string}
-          aria-disabled={isDisabled || undefined}
-          {...sharedProps}
           {...mergeProps(
             themeProps('token', {color, size}),
             focusOutlineProps.focusVisible(
@@ -368,7 +367,10 @@ export function Token({
             ),
             className,
             style,
-          )}>
+          )}
+          {...rest}
+          {...(isDisabled ? {'aria-disabled': true} : {})}
+          {...sharedProps}>
           {content}
         </LinkComponent>
       );
@@ -400,7 +402,6 @@ export function Token({
             {label}
           </span>
         }
-        {...sharedProps}
         {...mergeProps(
           themeProps('token', {color, size}),
           focusOutlineProps.focusWithin(
@@ -414,6 +415,8 @@ export function Token({
           className,
           style,
         )}
+        {...rest}
+        {...sharedProps}
       />
     );
   }
@@ -431,7 +434,6 @@ export function Token({
       <span
         ref={ref}
         onClick={isDisabled ? undefined : handleContainerClick}
-        {...sharedProps}
         {...mergeProps(
           themeProps('token', {color, size}),
           focusOutlineProps.focusWithin(
@@ -444,7 +446,9 @@ export function Token({
           ),
           className,
           style,
-        )}>
+        )}
+        {...rest}
+        {...sharedProps}>
         {icon}
         <button
           type="button"
@@ -468,7 +472,6 @@ export function Token({
   return (
     <span
       ref={ref}
-      {...sharedProps}
       {...mergeProps(
         themeProps('token', {color, size}),
         stylex.props(
@@ -480,7 +483,9 @@ export function Token({
         ),
         className,
         style,
-      )}>
+      )}
+      {...rest}
+      {...sharedProps}>
       {content}
     </span>
   );

package/src/Token/TokenLink.tsx

@@ -27,10 +27,11 @@
 
 import type {ReactNode, CSSProperties, Ref, HTMLAttributes} from 'react';
 import {useRef} from 'react';
-import {mergeRefs} from '../utils';
 import {useClickableContainer} from '../hooks/useClickableContainer';
 import type {LinkComponentType} from '../Link/types';
+import {composeEventHandlers} from '../utils';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 export interface TokenLinkProps extends HTMLAttributes<HTMLElement> {
   /** Ref forwarded to the container element. */
   ref?: Ref<HTMLElement>;
@@ -72,6 +73,8 @@ export function TokenLink({
   icon,
   endContent,
   removeButton,
+  onClick: onClickProp,
+  onMouseUp: onMouseUpProp,
   ...containerProps
 }: TokenLinkProps) {
   const containerRef = useRef<HTMLElement | null>(null);
@@ -86,10 +89,16 @@ export function TokenLink({
 
   return (
     <span
-      ref={mergeRefs(ref, containerRef)}
-      onClick={isDisabled ? undefined : onClick}
-      onMouseUp={isDisabled ? undefined : onMouseUp}
-      {...containerProps}>
+      ref={useMergedRefs(ref, containerRef)}
+      {...containerProps}
+      onClick={
+        isDisabled ? onClickProp : composeEventHandlers(onClickProp, onClick)
+      }
+      onMouseUp={
+        isDisabled
+          ? onMouseUpProp
+          : composeEventHandlers(onMouseUpProp, onMouseUp)
+      }>
       {icon}
       <LinkComponent
         ref={linkRef as Ref<HTMLAnchorElement>}

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -132,9 +132,20 @@ export const docs = {
     {
       name: 'maxMenuItems',
       type: 'number',
-      description: 'Maximum number of dropdown items to display.',
+      description: 'Maximum number of search results to display. The hasCreate entry is offered on top of them, so a menu can show one more than this.',
       default: '10',
     },
+    {
+      name: 'menuWidth',
+      type: 'number',
+      description: 'Fixed dropdown width in pixels. The menu never shrinks below its anchor width.',
+    },
+    {
+      name: 'minQueryLength',
+      type: 'number',
+      description: 'Minimum query length before the search source is queried. Below it no search runs, and the menu stays closed — unless hasCreate is set, in which case the "Create ..." entry is still offered, being derived from the typed text rather than fetched for it.',
+      default: '1',
+    },
     {
       name: 'emptySearchResultsText',
       type: 'string',
@@ -201,6 +212,22 @@ export const docs = {
       description:
         'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
     },
+    {
+      name: 'tokenOverflowBehavior',
+      type: "'none' | 'unfocusedInline' | 'unfocusedLayer'",
+      description: 'Controls how tokens overflow when the container is too narrow.',
+      default: "'none'",
+    },
+    {
+      name: 'onFocus',
+      type: '(e: FocusEvent<HTMLInputElement>) => void',
+      description: 'Fires when focus enters the tokenizer input.',
+    },
+    {
+      name: 'onBlur',
+      type: '(e: FocusEvent<HTMLInputElement>) => void',
+      description: 'Fires when focus leaves the tokenizer input.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -365,9 +392,20 @@ export const docsZh = {
     {
       name: 'maxMenuItems',
       type: 'number',
-      description: '\u4e0b\u62c9\u5217\u8868\u663e\u793a\u7684\u6700\u5927\u9879\u76ee\u6570\u3002',
+      description: '下拉列表显示的最大搜索结果数。“创建 ...”条目会在此之外额外提供，因此菜单可能比该数量多显示一项。',
       default: '10',
     },
+    {
+      name: 'menuWidth',
+      type: 'number',
+      description: '下拉菜单的固定像素宽度。菜单不会小于其锚点宽度。',
+    },
+    {
+      name: 'minQueryLength',
+      type: 'number',
+      description: '查询搜索源前的最小查询长度。低于该长度不会发起搜索，菜单保持关闭；但设置 hasCreate 时仍会提供“创建 ...”条目——该条目由输入的文本推导而来，并非通过搜索获取。',
+      default: '1',
+    },
     {
       name: 'emptySearchResultsText',
       type: 'string',
@@ -489,7 +527,9 @@ export const docsDense = {
     isOptional: 'Shows optional indicator on label.',
     labelTooltip: 'Tooltip on label.',
     hasEntriesOnFocus: 'Show bootstrap results on focus before typing.',
-    maxMenuItems: 'Max dropdown items to display.',
+    maxMenuItems: 'Max search results shown; the hasCreate entry sits on top of them.',
+    menuWidth: 'Fixed dropdown width in pixels.',
+    minQueryLength: 'Min query length before searching. Menu stays closed below it, except the hasCreate entry.',
     emptySearchResultsText: 'Text when search returns no results.',
     hasAutoFocus: 'Auto-focus input on mount.',
     size: 'Input+token size.',

package/src/Tokenizer/Tokenizer.test.tsx

@@ -94,6 +94,37 @@ const userSource: SearchSource = {
   bootstrap: () => users.slice(0, 3),
 };
 
+describe('Tokenizer minQueryLength', () => {
+  it('forwards the threshold to the typeahead engine', async () => {
+    const search = vi.fn((query: string) =>
+      users.filter(u => u.label.toLowerCase().includes(query.toLowerCase())),
+    );
+    render(
+      <Tokenizer
+        label="People"
+        searchSource={{search, bootstrap: () => []}}
+        value={[]}
+        onChange={() => {}}
+        minQueryLength={3}
+        debounceMs={0}
+      />,
+    );
+    const input = screen.getByRole('combobox');
+
+    fireEvent.change(input, {target: {value: 'Al'}});
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(search).not.toHaveBeenCalled();
+    expect(input).toHaveAttribute('aria-expanded', 'false');
+
+    fireEvent.change(input, {target: {value: 'Ali'}});
+    await waitFor(() => {
+      expect(input).toHaveAttribute('aria-expanded', 'true');
+    });
+  });
+});
+
 describe('Tokenizer', () => {
   it('forwards ref to the root field element', () => {
     let root: HTMLDivElement | null = null;
@@ -606,6 +637,136 @@ describe('Tokenizer', () => {
       bootstrap: () => [],
     };
 
+    it('still offers Create below minQueryLength, and does not search', async () => {
+      // The threshold exists to avoid a fetch too broad to be worth making.
+      // Creating costs no fetch, so a field that can create `QA` should not
+      // stop being able to just because a search for `QA` would match too
+      // much. Reported on #5385.
+      const search = vi.fn(() => []);
+      const onChange = vi.fn();
+      render(
+        <Tokenizer
+          label="Tags"
+          searchSource={{search, bootstrap: () => []}}
+          value={[]}
+          onChange={onChange}
+          hasCreate
+          minQueryLength={3}
+          debounceMs={0}
+        />,
+      );
+
+      const input = screen.getByRole('combobox');
+      await act(async () => {
+        fireEvent.change(input, {target: {value: 'QA'}});
+      });
+      await act(async () => {
+        await new Promise(r => setTimeout(r, 50));
+      });
+
+      // Offered...
+      expect(screen.queryByText('Create "QA"')).toBeInTheDocument();
+      // ...without the source ever being asked.
+      expect(search).not.toHaveBeenCalled();
+      // ...and it commits.
+      fireEvent.click(screen.getByText('Create "QA"'));
+      expect(onChange).toHaveBeenCalledWith(
+        [expect.objectContaining({id: 'QA', label: 'QA'})],
+        expect.objectContaining({type: 'create'}),
+      );
+    });
+
+    it('offers no menu below the threshold without hasCreate', async () => {
+      // The negative control for the case above: with nothing to derive from
+      // the text, a below-threshold query still opens nothing, and never
+      // reports "no results" for a query that was not searched.
+      const search = vi.fn(() => []);
+      render(
+        <Tokenizer
+          label="Tags"
+          searchSource={{search, bootstrap: () => []}}
+          value={[]}
+          onChange={() => {}}
+          minQueryLength={3}
+          debounceMs={0}
+        />,
+      );
+
+      const input = screen.getByRole('combobox');
+      await act(async () => {
+        fireEvent.change(input, {target: {value: 'QA'}});
+      });
+      await act(async () => {
+        await new Promise(r => setTimeout(r, 50));
+      });
+
+      expect(search).not.toHaveBeenCalled();
+      expect(input).toHaveAttribute('aria-expanded', 'false');
+      expect(screen.queryByText('No results found')).not.toBeInTheDocument();
+    });
+
+    it('does not offer Create below the threshold for a token already held', async () => {
+      render(
+        <Tokenizer
+          label="Tags"
+          searchSource={{search: () => [], bootstrap: () => []}}
+          value={[{id: 'QA', label: 'QA'}]}
+          onChange={() => {}}
+          hasCreate
+          minQueryLength={3}
+          debounceMs={0}
+        />,
+      );
+
+      const input = screen.getByRole('combobox');
+      await act(async () => {
+        fireEvent.change(input, {target: {value: 'QA'}});
+      });
+      await act(async () => {
+        await new Promise(r => setTimeout(r, 50));
+      });
+
+      expect(screen.queryByText('Create "QA"')).not.toBeInTheDocument();
+    });
+
+    it('offers Create on top of a full menu, not in place of a result', async () => {
+      // The Create entry is appended after the results are cut to
+      // `maxMenuItems`, so a full menu shows one more option rather than
+      // dropping its last result to make room. Deliberate: creating is a
+      // different capability from searching, and the cap exists to bound how
+      // many *results* a menu shows.
+      const many = Array.from({length: 20}, (_, i) => ({
+        id: `qa-${i}`,
+        label: `QA ${i}`,
+      }));
+      render(
+        <Tokenizer
+          label="Tags"
+          searchSource={{search: () => many, bootstrap: () => []}}
+          value={[]}
+          onChange={() => {}}
+          hasCreate
+          maxMenuItems={3}
+          debounceMs={0}
+        />,
+      );
+
+      const input = screen.getByRole('combobox');
+      await act(async () => {
+        fireEvent.change(input, {target: {value: 'QA'}});
+      });
+      await act(async () => {
+        await new Promise(r => setTimeout(r, 50));
+      });
+
+      // Queried off the document rather than by role: the popover renders
+      // into a layer that jsdom keeps out of the accessibility tree, which is
+      // why the tests around this one reach for text too.
+      const options = document.querySelectorAll('[role="option"]');
+      expect(options).toHaveLength(4);
+      expect(options[3]).toHaveTextContent('Create "QA"');
+    });
+
     it('shows a "Create" option when typing with hasCreate', async () => {
       render(
         <Tokenizer