@astryxdesign/core 0.2.0-canary.f306f13 → 0.2.0-canary.fc53ff7

package/src/Token/Token.tsx

@@ -9,6 +9,7 @@
  * @position Core implementation; consumed by index.ts, tested by Token.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Token/TokenLink.tsx (interactive wrapper for href+onRemove)
  * - /packages/core/src/Token/Token.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Token/Token.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Token/index.ts (exports if types change)
@@ -32,6 +33,7 @@ import {Icon} from '../Icon';
 import {mergeProps} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {useInteractiveRole} from '../hooks/useInteractiveRole';
+import {TokenLink} from './TokenLink';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -313,7 +315,9 @@ const colorStyles = stylex.create({
  * `<span>` container with an invisible `<button>` when `onClick` is provided.
  * The invisible button pattern provides real button semantics for accessibility
  * while the container uses `:focus-within` to show focus outlines around the
- * entire token.
+ * entire token. When both `href` and `onRemove` are provided, the same
+ * container pattern is used with an invisible `<a>` so the remove `<button>`
+ * renders as a sibling of the link rather than nested inside it.
  *
  * @example
  * ```
@@ -350,6 +354,20 @@ export function Token({
   // if onClick was provided — the popover attaches its own handler.
   const effectiveOnClick = onClick ?? (role === 'button' ? () => {} : null);
 
+  const removeButton = onRemove != null && (
+    <button
+      type="button"
+      aria-label={t('@astryx.token.remove', {label})}
+      onClick={e => {
+        e.stopPropagation();
+        onRemove(e);
+      }}
+      disabled={isDisabled}
+      {...stylex.props(styles.removeButton)}>
+      <Icon icon="close" size="xsm" color="inherit" />
+    </button>
+  );
+
   const content = (
     <>
       {icon}
@@ -358,19 +376,7 @@ export function Token({
         {label}
       </span>
       {endContent}
-      {onRemove != null && (
-        <button
-          type="button"
-          aria-label={t('@astryx.token.remove', {label})}
-          onClick={e => {
-            e.stopPropagation();
-            onRemove(e);
-          }}
-          disabled={isDisabled}
-          {...stylex.props(styles.removeButton)}>
-          <Icon icon="close" size="xsm" color="inherit" />
-        </button>
-      )}
+      {removeButton}
     </>
   );
 
@@ -381,11 +387,57 @@ export function Token({
   };
 
   if (role === 'link') {
+    if (onRemove == null) {
+      return (
+        <LinkComponent
+          ref={ref as React.Ref<HTMLAnchorElement>}
+          href={href as string}
+          aria-disabled={isDisabled || undefined}
+          {...sharedProps}
+          {...mergeProps(
+            themeProps('token', {color, size}),
+            stylex.props(
+              styles.base,
+              sizeStyles[size],
+              colorStyles[color],
+              styles.interactive,
+              isDisabled && styles.disabled,
+              xstyle,
+            ),
+            className,
+            style,
+          )}>
+          {content}
+        </LinkComponent>
+      );
+    }
+
+    // With a remove button, the link cannot be the root — nesting a <button>
+    // inside an <a> is invalid HTML (WCAG 4.1.2). Delegate to TokenLink, a
+    // non-presentational wrapper that renders a <span> container with the link
+    // and the remove button as siblings and wires up useClickableContainer so
+    // the whole token surface activates the link (including middle-click and
+    // cmd/ctrl-click to open in a new tab). Token itself stays presentational
+    // (no refs/effects) per the @astryx/presentational-component rule.
     return (
-      <LinkComponent
-        ref={ref as React.Ref<HTMLAnchorElement>}
+      <TokenLink
+        ref={ref}
         href={href as string}
-        aria-disabled={isDisabled || undefined}
+        isDisabled={isDisabled}
+        LinkComponent={LinkComponent}
+        icon={icon}
+        endContent={endContent}
+        removeButton={removeButton}
+        linkStyleProps={stylex.props(styles.invisibleButton)}
+        labelContent={
+          <span
+            {...stylex.props(
+              styles.label,
+              isLabelHidden && styles.labelHidden,
+            )}>
+            {label}
+          </span>
+        }
         {...sharedProps}
         {...mergeProps(
           themeProps('token', {color, size}),
@@ -394,14 +446,14 @@ export function Token({
             sizeStyles[size],
             colorStyles[color],
             styles.interactive,
+            styles.focusVisibleOutline,
             isDisabled && styles.disabled,
             xstyle,
           ),
           className,
           style,
-        )}>
-        {content}
-      </LinkComponent>
+        )}
+      />
     );
   }
 
@@ -448,19 +500,7 @@ export function Token({
           </span>
         </button>
         {endContent}
-        {onRemove != null && (
-          <button
-            type="button"
-            aria-label={t('@astryx.token.remove', {label})}
-            onClick={e => {
-              e.stopPropagation();
-              onRemove(e);
-            }}
-            disabled={isDisabled}
-            {...stylex.props(styles.removeButton)}>
-            <Icon icon="close" size="xsm" color="inherit" />
-          </button>
-        )}
+        {removeButton}
       </span>
     );
   }

package/src/Token/TokenLink.tsx

@@ -0,0 +1,107 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TokenLink.tsx
+ * @input Rendered token pieces (icon, label, endContent, remove button) plus
+ *   container/link styling props and the resolved LinkComponent
+ * @output Exports TokenLink, the interactive container for the href+onRemove Token variant
+ * @position Internal to Token; keeps Token.tsx presentational
+ *
+ * Token is a presentational component (see
+ * /internal/eslint-plugin-astryx/presentational-component.js) and must not use
+ * refs or effects. When a Token has both `href` and `onRemove`, the remove
+ * <button> must be a sibling of the link (nesting a button inside an anchor is
+ * invalid HTML — WCAG 4.1.2), so the surface becomes a clickable container that
+ * delegates to an inner link. That delegation needs refs, so it lives here.
+ *
+ * useClickableContainer gives the container middle-click and cmd/ctrl-click
+ * open-in-new-tab behavior for the link, ignores clicks on nested interactive
+ * elements (the remove button), and skips activation during text selection.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Token/Token.tsx (renders TokenLink for the href+onRemove case)
+ * - /packages/core/src/Token/Token.test.tsx (tests for delegated behavior)
+ */
+
+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';
+
+export interface TokenLinkProps extends HTMLAttributes<HTMLElement> {
+  /** Ref forwarded to the container element. */
+  ref?: Ref<HTMLElement>;
+  /** Link URL. */
+  href: string;
+  /** Whether the token is disabled. */
+  isDisabled: boolean;
+  /** Resolved link component (native `<a>` or a router link). */
+  LinkComponent: LinkComponentType;
+  /** `stylex.props()` output applied to the invisible inner link. */
+  linkStyleProps: {className?: string; style?: CSSProperties};
+  /** Visible (or visually hidden) label node rendered inside the link. */
+  labelContent: ReactNode;
+  /** Optional leading icon. */
+  icon?: ReactNode;
+  /** Content rendered after the label, before the remove button. */
+  endContent?: ReactNode;
+  /** The remove button node, rendered as a sibling of the link. */
+  removeButton: ReactNode;
+  /** Allow data-* attributes (e.g. data-testid, theme targets) on the container. */
+  [dataAttr: `data-${string}`]: unknown;
+}
+
+/**
+ * Interactive container for a Token that is both a link and removable.
+ *
+ * Renders a `<span>` wrapping an invisible inner link and the remove button as
+ * siblings. useClickableContainer delegates clicks on the surface to the link
+ * (including middle-click / cmd+click to open in a new tab) while the remove
+ * button keeps handling its own clicks.
+ */
+export function TokenLink({
+  ref,
+  href,
+  isDisabled,
+  LinkComponent,
+  linkStyleProps,
+  labelContent,
+  icon,
+  endContent,
+  removeButton,
+  ...containerProps
+}: TokenLinkProps) {
+  const containerRef = useRef<HTMLElement | null>(null);
+  const linkRef = useRef<HTMLElement | null>(null);
+
+  const {onClick, onMouseUp} = useClickableContainer({
+    containerRef,
+    interactiveRef: linkRef,
+    href,
+    disabled: isDisabled,
+  });
+
+  return (
+    <span
+      ref={mergeRefs(ref, containerRef)}
+      onClick={isDisabled ? undefined : onClick}
+      onMouseUp={isDisabled ? undefined : onMouseUp}
+      {...containerProps}>
+      {icon}
+      <LinkComponent
+        ref={linkRef as Ref<HTMLAnchorElement>}
+        href={href}
+        aria-disabled={isDisabled || undefined}
+        {...linkStyleProps}>
+        {labelContent}
+      </LinkComponent>
+      {endContent}
+      {removeButton}
+    </span>
+  );
+}
+
+TokenLink.displayName = 'TokenLink';

package/src/TopNav/TopNavMegaMenu.tsx

@@ -123,6 +123,18 @@ const styles = stylex.create({
       transform: 'translateY(-4px)',
     },
   },
+  // Clamp the anchored layer to the space available below the nav so a tall
+  // menu never runs off the bottom of the viewport. The layer is positioned
+  // with position-area: self-block-end, so its containing block spans from
+  // the nav's block-end to the viewport edge — 100% is exactly that space.
+  // The layer is a flex column so panelContainer can shrink and scroll its
+  // own content, keeping the surface radius/shadow static at the edges.
+  // Internal scroll is a stopgap until the mobile bottom-sheet lands.
+  panelViewportFit: {
+    display: 'flex',
+    flexDirection: 'column',
+    maxHeight: `calc(100% - ${spacingVars['--spacing-3']})`,
+  },
   // Visual styles for the panel content container.
   panelContainer: {
     backgroundColor: colorVars['--color-background-popover'],
@@ -132,6 +144,11 @@ const styles = stylex.create({
     borderRadius: radiusVars['--radius-container'],
     boxShadow: shadowVars['--shadow-low'],
     overflow: 'hidden',
+    // Allow the container to shrink inside the height-clamped layer so its
+    // content (panelContent) can scroll rather than overflow the viewport.
+    display: 'flex',
+    flexDirection: 'column',
+    minHeight: 0,
   },
   panelContent: {
     display: 'flex',
@@ -139,7 +156,14 @@ const styles = stylex.create({
     gap: spacingVars['--spacing-6'],
     paddingBlock: spacingVars['--spacing-3'],
     paddingInline: spacingVars['--spacing-3'],
-    maxWidth: 960,
+    // Clamp to the viewport (minus a gutter) so the anchored panel never
+    // overflows the screen edge on narrow viewports; caps at 960px otherwise.
+    maxWidth: `min(960px, calc(100dvw - ${spacingVars['--spacing-4']}))`,
+    boxSizing: 'border-box',
+    // Scroll internally when the menu is taller than the available space
+    // below the nav (paired with panelViewportFit on the layer).
+    overflowY: 'auto',
+    overscrollBehavior: 'contain',
   },
   menuWrapper: {
     flexGrow: 2,
@@ -484,7 +508,7 @@ function DefaultMegaMenu({
         {
           placement: 'below',
           alignment: slot,
-          xstyle: styles.panelAnimation,
+          xstyle: [styles.panelAnimation, styles.panelViewportFit],
         },
       )}
     </>

package/src/Typeahead/BaseTypeahead.tsx

@@ -157,6 +157,16 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
    */
   inputXStyle?: StyleXStyles;
 
+  /**
+   * Tab-order override for the input element. Typeahead passes `-1` while
+   * its selected-value token is shown: the input is visually collapsed
+   * (width 0 / opacity 0) but must stay programmatically focusable for
+   * token edit/clear interactions, so removing it from the Tab order is
+   * what prevents an invisible tab stop (WCAG 2.4.3 / 2.4.7). The input
+   * remains focusable via `.focus()` regardless of this value.
+   */
+  inputTabIndex?: number;
+
   /**
    * Ref to the anchor element for dropdown positioning.
    * The dropdown will be positioned relative to this element.
@@ -316,6 +326,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   ariaDescribedBy,
   ariaLabelledBy,
   inputXStyle,
+  inputTabIndex,
   anchorRef,
   onKeyDown: externalOnKeyDown,
   debounceMs = 150,
@@ -748,6 +759,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         aria-describedby={ariaDescribedBy}
         aria-labelledby={ariaLabelledBy}
         aria-disabled={isFocusableDisabled ? 'true' : undefined}
+        tabIndex={inputTabIndex}
         value={query}
         onChange={handleInputChange}
         onPointerDown={() => {

package/src/Typeahead/Typeahead.test.tsx

@@ -737,6 +737,68 @@ describe('Typeahead edit mode', () => {
   });
 });
 
+describe('Typeahead collapsed input tab order', () => {
+  it('removes the invisible input from the Tab order while a token is shown', () => {
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={() => {}}
+      />,
+    );
+    // While the token is shown the input is collapsed (width 0 / opacity 0);
+    // it must stay programmatically focusable for token interactions but must
+    // not be an invisible Tab stop (WCAG 2.4.3 / 2.4.7).
+    expect(screen.getByRole('combobox')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('Tab from the token skips the invisible input', async () => {
+    const user = userEvent.setup();
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={() => {}}
+      />,
+    );
+    // Focus the token's internal button, then Tab away — focus must not land
+    // on the visually hidden combobox input.
+    const tokenButton = screen.getByRole('button', {name: fruits[0].label});
+    tokenButton.focus();
+    await user.tab();
+    expect(screen.getByRole('combobox')).not.toHaveFocus();
+  });
+
+  it('keeps the input in the Tab order when no token is shown', () => {
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+      />,
+    );
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex');
+  });
+
+  it('restores the input to the Tab order in edit mode', () => {
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={() => {}}
+      />,
+    );
+    // Entering edit mode removes the token and uncollapses the input
+    const tokenText = screen.getByText(fruits[0].label);
+    fireEvent.click(tokenText.closest('div')!);
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex');
+  });
+});
+
 describe('BaseTypeahead paste behavior', () => {
   it('pasting text triggers search results like typing', async () => {
     const user = userEvent.setup();

package/src/Typeahead/Typeahead.tsx

@@ -467,6 +467,12 @@ export function Typeahead<T extends SearchableItem>({
           anchorRef={wrapperRef}
           onKeyDown={handleKeyDown}
           inputXStyle={showToken ? styles.inputHidden : undefined}
+          // While the token is shown the input is collapsed (width 0 /
+          // opacity 0) — take it out of the Tab order so keyboard users
+          // don't hit an invisible stop (WCAG 2.4.3 / 2.4.7). It stays
+          // programmatically focusable: entering edit mode and clearing
+          // both refocus it after it uncollapses.
+          inputTabIndex={showToken ? -1 : undefined}
           size={size}
         />
         {hasClear && value && !isDisabled && (

package/src/__tests__/forcedColors.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file forcedColors.ts
+ * @input Uses the jsdom document (StyleX dev runtime injects rules into it)
+ * @output Exports getForcedColorsRules, getAllInjectedCss test helpers
+ * @position Shared test utility for asserting forced-colors style output
+ *
+ * jsdom cannot emulate `@media (forced-colors: active)` rendering, so
+ * component tests assert the next-best thing: that the StyleX dev runtime
+ * (runtimeInjection in vitest.config.ts) actually injected the forced-colors
+ * rules a component relies on for Windows High Contrast support (WCAG 1.4.11).
+ * Visual behavior needs manual verification in a forced-colors environment.
+ */
+
+/**
+ * Collects the cssText of every injected CSS rule scoped to
+ * `@media (forced-colors: active)`, including rules nested in other
+ * conditions. Returns one string for substring assertions.
+ */
+export function getForcedColorsRules(): string {
+  const chunks: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRule[];
+    try {
+      rules = Array.from(sheet.cssRules);
+    } catch {
+      continue;
+    }
+    for (const rule of rules) {
+      if (rule.cssText.includes('forced-colors: active')) {
+        chunks.push(rule.cssText);
+      }
+    }
+  }
+  return chunks.join('\n');
+}
+
+/**
+ * Collects the cssText of every injected CSS rule, regardless of condition.
+ * Use to assert declarations that live OUTSIDE `@media (forced-colors: active)`
+ * yet still exist for forced-colors support — e.g. `forced-color-adjust: none`
+ * (an unconditional declaration) or a hover tint gated behind
+ * `(forced-colors: none)` so it cannot override the forced-colors state.
+ */
+export function getAllInjectedCss(): string {
+  const chunks: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRule[];
+    try {
+      rules = Array.from(sheet.cssRules);
+    } catch {
+      continue;
+    }
+    for (const rule of rules) {
+      chunks.push(rule.cssText);
+    }
+  }
+  return chunks.join('\n');
+}