@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/src/InputGroup/InputGroupContext.ts

@@ -4,19 +4,24 @@
 
 /**
  * @file InputGroupContext.ts
- * @input None (pure context definition)
+ * @input React createContext/use
  * @output Exports InputGroup context and useInputGroup hook
- * @position Shared context; consumed by input components for group-aware styling
+ * @position Shared context; consumed by input components for group-aware styling and ARIA associations
  */
 
 import {createContext, use} from 'react';
 
 export interface InputGroupContextValue {
   isInGroup: true;
+  /** ID of the group label element, for aria-labelledby composition. */
+  labelID: string;
+  /** IDs of helper/status text owned by the group, for aria-describedby composition. */
+  describedByIDs?: string;
 }
 
-export const InputGroupContext =
-  createContext<InputGroupContextValue | null>(null);
+export const InputGroupContext = createContext<InputGroupContextValue | null>(
+  null,
+);
 InputGroupContext.displayName = 'InputGroupContext';
 
 /**

package/src/InputGroup/index.ts

@@ -16,3 +16,4 @@ export {InputGroupText} from './InputGroupText';
 export type {InputGroupTextProps} from './InputGroupText';
 
 export {useInputGroup} from './InputGroupContext';
+export type {InputGroupContextValue} from './InputGroupContext';

package/src/Kbd/Kbd.test.tsx

@@ -72,10 +72,28 @@ describe('Kbd', () => {
     expect(screen.getByText('Esc')).toBeInTheDocument();
   });
 
-  it('is aria-hidden', () => {
-    const {container} = render(<Kbd keys="mod+k" />);
-    const wrapper = container.firstChild as HTMLElement;
-    expect(wrapper.getAttribute('aria-hidden')).toBe('true');
+  it('exposes a spoken accessible name and hides the glyphs (obs-1)', () => {
+    render(<Kbd keys="mod+shift+k" />);
+    // The wrapper carries a screen-reader name built from spoken key labels
+    // (jsdom is non-Mac, so mod → "Control").
+    const img = screen.getByRole('img');
+    expect(img).toHaveAttribute('aria-label', 'Control + Shift + K');
+    // The visual glyph elements are hidden from assistive tech.
+    const glyphs = img.querySelectorAll('kbd');
+    glyphs.forEach(g => expect(g).toHaveAttribute('aria-hidden', 'true'));
+    expect(img).not.toHaveAttribute('aria-hidden');
+  });
+
+  it('uses "Command" in the accessible name for mod on Mac', () => {
+    Object.defineProperty(navigator, 'platform', {
+      value: 'MacIntel',
+      configurable: true,
+    });
+    render(<Kbd keys="mod+k" />);
+    expect(screen.getByRole('img')).toHaveAttribute(
+      'aria-label',
+      'Command + K',
+    );
   });
 
   it('uppercases unknown keys', () => {

package/src/Kbd/Kbd.tsx

@@ -45,7 +45,7 @@ const styles = stylex.create({
     backgroundColor: colorVars['--color-neutral'],
     borderBottomWidth: '2px',
     borderBottomStyle: 'solid',
-    borderBottomColor: colorVars['--color-border'],
+    borderBottomColor: colorVars['--color-border-emphasized'],
     color: colorVars['--color-text-secondary'],
     fontFamily: typographyVars['--font-family-body'],
     fontSize: typeScaleVars['--text-supporting-size'],
@@ -87,6 +87,33 @@ function getKeyDisplay(key: string, isMac: boolean): string {
   return KEY_DISPLAY[key] ?? key.toUpperCase();
 }
 
+/**
+ * Spoken-word labels for screen readers. The visual `KEY_DISPLAY` uses glyphs
+ * (⌘, ⇧, ↵, …) that assistive tech cannot announce meaningfully, so the
+ * accessible name for the shortcut is built from these words instead.
+ */
+const KEY_LABEL: Record<string, string> = {
+  ctrl: 'Control',
+  alt: 'Alt',
+  shift: 'Shift',
+  enter: 'Enter',
+  backspace: 'Backspace',
+  escape: 'Escape',
+  tab: 'Tab',
+  up: 'Up arrow',
+  down: 'Down arrow',
+  left: 'Left arrow',
+  right: 'Right arrow',
+  plus: 'Plus',
+};
+
+function getKeyLabel(key: string, isMac: boolean): string {
+  if (key === 'mod') {
+    return isMac ? 'Command' : 'Control';
+  }
+  return KEY_LABEL[key] ?? key.toUpperCase();
+}
+
 function subscribeToPlatformChanges(): () => void {
   return () => {};
 }
@@ -146,14 +173,7 @@ export interface KbdProps extends BaseProps<HTMLSpanElement> {
  * <Kbd keys="mod+k" />
  * ```
  */
-export function Kbd({
-  keys,
-  ref,
-  xstyle,
-  className,
-  style,
-  ...rest
-}: KbdProps) {
+export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
   const isMac = useSyncExternalStore(
     subscribeToPlatformChanges,
     detectMac,
@@ -162,19 +182,24 @@ export function Kbd({
 
   const parts = keys.split('+').map(key => key.trim().toLowerCase());
 
+  // Screen-reader name: the joined spoken labels (e.g. "Command + K"), since
+  // the visual glyphs below are announced meaninglessly by assistive tech.
+  const accessibleName = parts.map(key => getKeyLabel(key, isMac)).join(' + ');
+
   return (
     <span
       ref={ref}
+      role="img"
+      aria-label={accessibleName}
       {...rest}
       {...mergeProps(
         themeProps('kbd'),
         stylex.props(styles.wrapper, xstyle),
         className,
         style,
-      )}
-      aria-hidden="true">
+      )}>
       {parts.map(key => (
-        <kbd key={key} {...stylex.props(styles.kbd)}>
+        <kbd key={key} aria-hidden="true" {...stylex.props(styles.kbd)}>
           {getKeyDisplay(key, isMac)}
         </kbd>
       ))}

package/src/Layer/anchorName.test.ts

@@ -0,0 +1,146 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file anchorName.test.ts
+ * @input Uses vitest, anchorName utilities
+ * @output Unit tests for anchor-name list manipulation helpers
+ * @position Testing; validates anchorName.ts implementation
+ *
+ * SYNC: When anchorName.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {
+  readAnchorNames,
+  writeAnchorNames,
+  addAnchorName,
+  removeAnchorName,
+} from './anchorName';
+
+function createMockElement(): HTMLElement {
+  const el = document.createElement('div');
+  return el;
+}
+
+describe('readAnchorNames', () => {
+  it('returns empty array for element with no anchor-name', () => {
+    const el = createMockElement();
+    expect(readAnchorNames(el)).toEqual([]);
+  });
+
+  it('reads a single anchor name', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName = '--layer-1';
+    expect(readAnchorNames(el)).toEqual(['--layer-1']);
+  });
+
+  it('reads multiple comma-separated anchor names', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName =
+      '--layer-1, --layer-2, --layer-3';
+    expect(readAnchorNames(el)).toEqual([
+      '--layer-1',
+      '--layer-2',
+      '--layer-3',
+    ]);
+  });
+
+  it('trims whitespace around names', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName =
+      '  --layer-1 ,  --layer-2  ';
+    expect(readAnchorNames(el)).toEqual(['--layer-1', '--layer-2']);
+  });
+
+  it('returns empty array for empty string value', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName = '';
+    expect(readAnchorNames(el)).toEqual([]);
+  });
+});
+
+describe('writeAnchorNames', () => {
+  it('writes names as comma-separated list', () => {
+    const el = createMockElement();
+    writeAnchorNames(el, ['--layer-1', '--layer-2']);
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe(
+      '--layer-1, --layer-2',
+    );
+  });
+
+  it('writes empty string for empty array', () => {
+    const el = createMockElement();
+    writeAnchorNames(el, []);
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe('');
+  });
+});
+
+describe('addAnchorName', () => {
+  it('adds name to element with no existing anchors', () => {
+    const el = createMockElement();
+    addAnchorName(el, '--layer-1');
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe(
+      '--layer-1',
+    );
+  });
+
+  it('appends name to existing anchor list', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName = '--layer-1';
+    addAnchorName(el, '--layer-2');
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe(
+      '--layer-1, --layer-2',
+    );
+  });
+
+  it('does not duplicate an already-present name', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName = '--layer-1';
+    addAnchorName(el, '--layer-1');
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe(
+      '--layer-1',
+    );
+  });
+
+  it('supports multiple layers sharing one element', () => {
+    const el = createMockElement();
+    addAnchorName(el, '--menu-1');
+    addAnchorName(el, '--menu-2');
+    addAnchorName(el, '--menu-3');
+    expect(readAnchorNames(el)).toEqual(['--menu-1', '--menu-2', '--menu-3']);
+  });
+});
+
+describe('removeAnchorName', () => {
+  it('removes name from a multi-anchor list', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName =
+      '--layer-1, --layer-2, --layer-3';
+    removeAnchorName(el, '--layer-2');
+    expect(readAnchorNames(el)).toEqual(['--layer-1', '--layer-3']);
+  });
+
+  it('removes the last remaining name, leaving empty string', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName = '--layer-1';
+    removeAnchorName(el, '--layer-1');
+    expect((el.style as unknown as Record<string, string>).anchorName).toBe('');
+  });
+
+  it('is a no-op if name is not present', () => {
+    const el = createMockElement();
+    (el.style as unknown as Record<string, string>).anchorName =
+      '--layer-1, --layer-2';
+    removeAnchorName(el, '--layer-3');
+    expect(readAnchorNames(el)).toEqual(['--layer-1', '--layer-2']);
+  });
+
+  it('handles multiple add/remove cycles correctly', () => {
+    const el = createMockElement();
+    addAnchorName(el, '--menu-a');
+    addAnchorName(el, '--menu-b');
+    removeAnchorName(el, '--menu-a');
+    addAnchorName(el, '--menu-c');
+    expect(readAnchorNames(el)).toEqual(['--menu-b', '--menu-c']);
+  });
+});

package/src/Layer/anchorName.ts

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file anchorName.ts
+ * @input HTMLElement with CSS anchor-name property
+ * @output Helpers for managing comma-separated anchor-name lists
+ * @position Utility; used by useLayer for multi-anchor support
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/useLayer.tsx (imports from here)
+ */
+
+/**
+ * CSS `anchor-name` is a comma-separated list, so multiple layers can anchor to
+ * the same element (e.g. several TopNavMegaMenus anchored to one <nav>). These
+ * helpers add/remove a single layer's anchor id without clobbering the others —
+ * overwriting the whole property would break every sibling layer's positioning.
+ */
+
+export function readAnchorNames(el: HTMLElement): string[] {
+  const value =
+    (el.style as unknown as Record<string, string>).anchorName ?? '';
+  return value
+    .split(',')
+    .map(name => name.trim())
+    .filter(Boolean);
+}
+
+export function writeAnchorNames(el: HTMLElement, names: string[]): void {
+  (el.style as unknown as Record<string, string>).anchorName = names.join(', ');
+}
+
+export function addAnchorName(el: HTMLElement, name: string): void {
+  const names = readAnchorNames(el);
+  if (!names.includes(name)) {
+    names.push(name);
+    writeAnchorNames(el, names);
+  }
+}
+
+export function removeAnchorName(el: HTMLElement, name: string): void {
+  writeAnchorNames(
+    el,
+    readAnchorNames(el).filter(existing => existing !== name),
+  );
+}

package/src/Layer/layerAnimations.stylex.ts

@@ -72,22 +72,38 @@ const animationBase = {
  *
  * Keyed by LayerPlacement ('above' | 'below' | 'start' | 'end')
  * for easy lookup: `layerAnimations[placement]`.
+ *
+ * Each entry disables its keyframe animation under
+ * `prefers-reduced-motion: reduce` so the layer appears instantly instead of
+ * translating/scaling in (infra-6).
  */
 export const layerAnimations = stylex.create({
   below: {
-    animationName: enterBelow,
+    animationName: {
+      default: enterBelow,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
     ...animationBase,
   },
   above: {
-    animationName: enterAbove,
+    animationName: {
+      default: enterAbove,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
     ...animationBase,
   },
   end: {
-    animationName: enterEnd,
+    animationName: {
+      default: enterEnd,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
     ...animationBase,
   },
   start: {
-    animationName: enterStart,
+    animationName: {
+      default: enterStart,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
     ...animationBase,
   },
 });

package/src/Layer/useLayer.doc.mjs

@@ -78,7 +78,7 @@ export const docs = {
       name: 'render',
       type: '(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode',
       description:
-        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode.',
+        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal.',
     },
   ],
   usage: {
@@ -95,6 +95,11 @@ export const docs = {
         description:
           'Build on higher-level components like Popover, HoverCard, and Tooltip for common overlay patterns.',
       },
+      {
+        guidance: true,
+        description:
+          'Rely on the Popover API top layer to escape ancestor clipping and stacking: render the layer inline (no portal) so it inherits the trigger\'s theme cascade and keeps a natural focus order. Use `as: "span"` when the layer must be valid inside inline contexts like a paragraph.',
+      },
       {
         guidance: false,
         description:
@@ -125,7 +130,7 @@ export const docsDense = {
     hide: 'hide layer.',
     isOpen: 'whether layer is open.',
     id: 'unique ARIA id.',
-    render: 'renders popover element; pass placement/alignment or x/y.',
+    render: 'renders popover element; pass placement/alignment or x/y. Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal.',
   },
   usage: {
     description:
@@ -139,6 +144,11 @@ export const docsDense = {
         guidance: true,
         description: 'Build on Popover/HoverCard/Tooltip for common overlay patterns.',
       },
+      {
+        guidance: true,
+        description:
+          'Rely on the Popover API top layer to escape clipping/stacking: render inline (no portal) to inherit the trigger theme cascade and natural focus order. Use `as: "span"` when the layer must be valid in inline contexts like a paragraph.',
+      },
       {
         guidance: false,
         description:

package/src/Layer/useLayer.tsx

@@ -15,6 +15,7 @@
 
 import React, {
   useCallback,
+  useEffect,
   useId,
   useRef,
   useState,
@@ -23,6 +24,7 @@ import React, {
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
+import {addAnchorName, removeAnchorName} from './anchorName';
 import {typographyVars} from '../theme/tokens.stylex';
 
 const styles = stylex.create({
@@ -65,6 +67,12 @@ export type LayerAlignment = 'start' | 'center' | 'end';
 export interface ContextRenderProps {
   placement?: LayerPlacement;
   alignment?: LayerAlignment;
+  /**
+   * ARIA role applied to the popover container (e.g. `'tooltip'`). Lets
+   * consumers complete the ARIA pattern and gives test tooling a stable,
+   * non-hashed selector for the layer.
+   */
+  role?: string;
   /**
    * StyleX styles for the popover container.
    */
@@ -79,6 +87,29 @@ export interface ContextRenderProps {
    * Merged after StyleX and anchor positioning styles.
    */
   style?: React.CSSProperties;
+  /**
+   * HTML tag to render the popover container as.
+   *
+   * Defaults to `'div'`. Pass `'span'` when the layer must render inline-safe
+   * markup — e.g. a `HoverCard` wrapping inline text inside a `<p>`. A `<span>`
+   * is phrasing content, so it stays put in the DOM tree instead of being
+   * reparented out of a paragraph by the HTML parser, which keeps server and
+   * client markup identical. The Popover API and CSS anchor positioning work
+   * the same on either tag.
+   *
+   * @default 'div'
+   */
+  as?: 'div' | 'span';
+  /**
+   * Pointer-enter handler attached to the popover container itself. Lets a
+   * consumer keep a hover-driven layer open while the pointer is over the
+   * surface (e.g. Tooltip/HoverCard "hoverable" behavior — WCAG 1.4.13).
+   */
+  onMouseEnter?: React.MouseEventHandler<HTMLElement>;
+  /**
+   * Pointer-leave handler attached to the popover container itself.
+   */
+  onMouseLeave?: React.MouseEventHandler<HTMLElement>;
 }
 
 /**
@@ -311,16 +342,14 @@ export function useLayer(
   const ref: RefCallback<HTMLElement> | undefined =
     mode === 'context'
       ? (el: HTMLElement | null) => {
-          // Cleanup previous element
-          if (triggerRef.current) {
-            (
-              triggerRef.current.style as unknown as Record<string, string>
-            ).anchorName = '';
+          // Remove only THIS layer's anchor name from the previous element so
+          // other layers sharing the same trigger keep their anchors.
+          if (triggerRef.current && triggerRef.current !== el) {
+            removeAnchorName(triggerRef.current, anchorId);
           }
 
           if (el) {
-            (el.style as unknown as Record<string, string>).anchorName =
-              anchorId;
+            addAnchorName(el, anchorId);
           }
 
           triggerRef.current = el;
@@ -349,26 +378,76 @@ export function useLayer(
     [onHide],
   );
 
-  // Ref callback for popover element — sets up toggle listener
+  // Ref callback for popover element — sets up the `toggle` listener.
+  // Tracks the element + handler currently bound so the listener is removed
+  // when the element detaches or when `handleToggle`'s identity changes (a new
+  // `onHide` prop), preventing stale-closure listeners from accumulating on the
+  // same element (infra-10).
+  const listenedElRef = useRef<HTMLElement | null>(null);
+  const listenedHandlerRef = useRef<((e: Event) => void) | null>(null);
+
+  const bindToggleListener = useCallback(
+    (el: HTMLElement | null, handler: (e: Event) => void) => {
+      if (
+        listenedElRef.current &&
+        listenedHandlerRef.current &&
+        (listenedElRef.current !== el || listenedHandlerRef.current !== handler)
+      ) {
+        listenedElRef.current.removeEventListener(
+          'toggle',
+          listenedHandlerRef.current,
+        );
+        listenedElRef.current = null;
+        listenedHandlerRef.current = null;
+      }
+      if (el && listenedElRef.current !== el) {
+        el.addEventListener('toggle', handler);
+        listenedElRef.current = el;
+        listenedHandlerRef.current = handler;
+      }
+    },
+    [],
+  );
+
   const popoverRefCallback = useCallback(
     (el: HTMLElement | null) => {
       popoverRef.current = el;
-      if (el) {
-        el.addEventListener('toggle', handleToggle);
-      }
+      bindToggleListener(el, handleToggle);
     },
-    [handleToggle],
+    [handleToggle, bindToggleListener],
   );
 
+  // Re-bind when the handler identity changes while the element stays mounted,
+  // and detach on unmount.
+  useEffect(() => {
+    if (popoverRef.current) {
+      bindToggleListener(popoverRef.current, handleToggle);
+    }
+    return () => {
+      if (listenedElRef.current && listenedHandlerRef.current) {
+        listenedElRef.current.removeEventListener(
+          'toggle',
+          listenedHandlerRef.current,
+        );
+        listenedElRef.current = null;
+        listenedHandlerRef.current = null;
+      }
+    };
+  }, [handleToggle, bindToggleListener]);
+
   // Render function for context mode
   const renderContext = useCallback(
     (children: ReactNode, props?: ContextRenderProps) => {
       const {
         placement = 'above',
         alignment = 'center',
+        role,
         xstyle,
         className: extraClassName,
         style: extraStyle,
+        as: Container = 'div',
+        onMouseEnter,
+        onMouseLeave,
       } = props || {};
 
       // CSS anchor positioning (dynamic, not in StyleX)
@@ -383,15 +462,21 @@ export function useLayer(
         ? `${extraClassName} ${stylexResult.className ?? ''}`
         : stylexResult.className;
 
+      // Render as the requested tag. A `span` keeps the layer phrasing content
+      // so it is valid (and stays put on hydration) inside inline contexts like
+      // a `<p>`; `div` remains the default for block layers.
       return (
-        <div
+        <Container
           ref={popoverRefCallback}
           id={id}
+          role={role}
           popover={lightDismiss ? 'auto' : 'manual'}
           className={combinedClassName}
-          style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}>
+          style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}
+          onMouseEnter={onMouseEnter}
+          onMouseLeave={onMouseLeave}>
           {children}
-        </div>
+        </Container>
       );
     },
     [anchorId, id, lightDismiss, popoverRefCallback],

package/src/Layout/Layout.doc.mjs

@@ -30,7 +30,7 @@ export const docs = {
       name: 'content',
       type: 'ReactNode',
       description:
-        'Main content area (center). Children passed to `<Layout>` render here too — `<Layout>{main}</Layout>` is shorthand for `<Layout content={main} />`.',
+        'Main content area (center). Children passed to `<Layout>` render here too: `<Layout>{main}</Layout>` is shorthand for `<Layout content={main} />`.',
       slotElements: [
         {
           __element: 'LayoutContent',