@astryxdesign/core 0.7.7-canary.c0929c8 → 0.7.7-canary.c19ca12

package/src/InfoTip/InfoTip.doc.mjs

@@ -0,0 +1,192 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'InfoTip',
+  displayName: 'Info Tip',
+  // Keeps the registry route InfoTip had as a canary-only Lab component.
+  registry: {aliases: ['lab/info-tip']},
+  category: 'Feedback & Status',
+  keywords: [
+    'info',
+    'tooltip',
+    'help',
+    'hint',
+    'affordance',
+    'icon',
+    'label',
+    'field',
+    'metric',
+    'definition',
+  ],
+  props: [
+    {
+      name: 'content',
+      type: 'ReactNode',
+      description:
+        "Content to display in the tooltip. Typically short, non-interactive text. Mirrors Tooltip's content prop.",
+      required: true,
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description:
+        'Accessible name for the trigger button. Defaults to the translated "More information".',
+      default: "'More information'",
+    },
+    {
+      name: 'size',
+      type: "'xsm' | 'sm' | 'md' | 'lg'",
+      description:
+        'Size of the info icon (12px, 16px, 20px, 24px). Maps 1:1 to Icon sizes.',
+      default: "'sm'",
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
+    },
+  ],
+  usage: {
+    description:
+      'An info icon that reveals help: a small "i" button. Hover and keyboard focus preview the help, and a click, tap, Enter, or Space pins it open until Escape, a second press, a press outside, or focus leaving. Use it next to labels, values, and metrics for permission notes, metric definitions, and field help. Its value over hand-composing Icon inside Tooltip is the pre-wired accessible trigger: a real button with an aria-label, Tab-reachable, tooltip on hover AND focus AND tap, and Escape dismissal.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Keep tooltip content concise, plain, and non-interactive; use Popover or HoverCard for links and buttons.',
+      },
+      {
+        guidance: true,
+        description:
+          'Override label when "More information" is too generic, e.g. "About this metric".',
+      },
+      {
+        guidance: true,
+        description:
+          'Rely on InfoTip rather than a hand-rolled info button on touch: it pins its help on a press, so a tap, a click, Enter, or Space pins the tooltip even though the trigger is a button, and a tap outside dismisses it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hand-compose Icon inside Tooltip for info affordances; the bare Icon is aria-hidden and unfocusable, so keyboard and screen-reader users never see it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use InfoTip for essential information users must see to complete a task; put that text inline instead.',
+      },
+    ],
+  },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docsZh = {
+  name: 'InfoTip',
+  displayName: 'Info Tip',
+  props: [
+    {
+      name: 'content',
+      type: 'ReactNode',
+      description:
+        '工具提示中显示的内容。通常为简短的非交互文本。与 Tooltip 的 content 属性一致。',
+      required: true,
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: '触发按钮的无障碍名称。默认为翻译后的“More information”。',
+      default: "'More information'",
+    },
+    {
+      name: 'size',
+      type: "'xsm' | 'sm' | 'md' | 'lg'",
+      description:
+        '信息图标的尺寸（12px、16px、20px、24px）。与 Icon 尺寸一一对应。',
+      default: "'sm'",
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        '用于布局自定义的 StyleX 样式（边距、定位、尺寸）。必须是 stylex.create() 的值，不能是内联样式对象如 style={{}}。',
+    },
+  ],
+  usage: {
+    description:
+      'An info icon that reveals help: a small "i" button. Hover and keyboard focus preview the help, and a click, tap, Enter, or Space pins it open until Escape, a second press, a press outside, or focus leaving. Use it next to labels, values, and metrics for permission notes, metric definitions, and field help.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Keep tooltip content concise, plain, and non-interactive; use Popover or HoverCard for links and buttons.',
+      },
+      {
+        guidance: true,
+        description:
+          'Override label when "More information" is too generic, e.g. "About this metric".',
+      },
+      {
+        guidance: true,
+        description:
+          'Rely on InfoTip rather than a hand-rolled info button on touch: it pins its help on a press, so a tap, a click, Enter, or Space pins the tooltip even though the trigger is a button, and a tap outside dismisses it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hand-compose Icon inside Tooltip for info affordances; the bare Icon is aria-hidden and unfocusable, so keyboard and screen-reader users never see it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use InfoTip for essential information users must see to complete a task; put that text inline instead.',
+      },
+    ],
+  },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
+  description:
+    'Inline info-icon help affordance: accessible "i" button trigger pre-wired into a Tooltip.',
+  usage: {
+    description:
+      'A small "i" button: hover and keyboard focus preview the help; a click, tap, Enter, or Space pins it open. Use next to labels, values, and metrics for permission notes, metric definitions, and field help. Pre-wired accessible trigger: real button, aria-label, Tab-reachable, tooltip on hover AND focus AND tap, Escape dismissal.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Keep tooltip content concise, plain, and non-interactive; use Popover or HoverCard for links and buttons.',
+      },
+      {
+        guidance: true,
+        description:
+          'Override label when "More information" is too generic, e.g. "About this metric".',
+      },
+      {
+        guidance: true,
+        description:
+          'Rely on InfoTip rather than a hand-rolled info button on touch: it pins its help on a press, so a tap, a click, Enter, or Space pins the tooltip even though the trigger is a button, and a tap outside dismisses it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Hand-compose Icon inside Tooltip for info affordances; the bare Icon is aria-hidden and unfocusable.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use InfoTip for essential information users must see to complete a task; put that text inline instead.',
+      },
+    ],
+  },
+  propDescriptions: {
+    content:
+      'Tooltip content. Short, non-interactive text. Mirrors Tooltip content prop.',
+    label:
+      "Accessible name for the trigger button. Default: the translated 'More information'.",
+    size: 'Info icon size (12/16/20/24px). Maps 1:1 to Icon sizes.',
+  },
+};

package/src/InfoTip/InfoTip.tsx

@@ -0,0 +1,186 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file InfoTip.tsx
+ * @input Uses React, StyleX, Tooltip, Icon, useComponentTranslator, the shared
+ *   touch hit area, color/spacing/radius/duration/ease tokens
+ * @output Exports InfoTip component, InfoTipProps, InfoTipSize types
+ * @position Core implementation; consumed by index.ts, tested by
+ *   InfoTip.test.tsx; `@astryxdesign/lab` re-exports it, deprecated
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/InfoTip/InfoTip.doc.mjs (props table, features)
+ * - /docs/specs/components/InfoTip/InfoTip.spec.md (contract)
+ * - /packages/core/src/InfoTip/InfoTip.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/InfoTip/index.ts (exports if types change)
+ */
+
+import {useCallback, type ReactNode, type Ref} from 'react';
+import * as stylex from '@stylexjs/stylex';
+
+import type {BaseProps} from '../BaseProps';
+import {useMergedRefs} from '../hooks/useMergedRefs';
+import {Icon, type IconSize} from '../Icon/Icon';
+import {TooltipWithTriggerBehavior} from '../Tooltip/Tooltip';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/InfoTip/InfoTip.generated';
+import {
+  colorVars,
+  durationVars,
+  easeVars,
+  radiusVars,
+  spacingVars,
+} from '../theme/tokens.stylex';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {mergeProps} from '../utils/mergeProps';
+import {watchHitArea, writeHitInsets} from '../utils/hitArea';
+
+registerEnglishFallback(english);
+
+/**
+ * Size of the info icon. Maps 1:1 to Icon sizes
+ * (xsm: 12px, sm: 16px, md: 20px, lg: 24px).
+ */
+export type InfoTipSize = IconSize;
+
+export interface InfoTipProps extends Pick<
+  BaseProps,
+  'xstyle' | 'className' | 'style'
+> {
+  /** Ref forwarded to the info button. */
+  ref?: Ref<HTMLButtonElement>;
+  /**
+   * The help the button reveals. Short, noninteractive text; for links or
+   * buttons, use HoverCard.
+   */
+  content: ReactNode;
+  /**
+   * Accessible name of the button.
+   * @default A translated "More information"
+   */
+  label?: string;
+  /**
+   * Size of the info icon.
+   * @default 'sm'
+   */
+  size?: InfoTipSize;
+}
+
+const styles = stylex.create({
+  trigger: {
+    position: 'relative',
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    verticalAlign: 'middle',
+    padding: spacingVars['--spacing-0-5'],
+    margin: 0,
+    borderStyle: 'none',
+    backgroundColor: 'transparent',
+    borderRadius: radiusVars['--radius-full'],
+    cursor: {
+      default: 'pointer',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
+    color: {
+      default: colorVars['--color-icon-secondary'],
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
+        default: null,
+        '@media (hover: hover)': colorVars['--color-icon-primary'],
+      },
+    },
+    transitionProperty: 'color',
+    transitionDuration: durationVars['--duration-fast'],
+    transitionTimingFunction: easeVars['--ease-standard'],
+  },
+  // The invisible hit area. Under a coarse pointer, the shared hit area writes
+  // how far the button may grow toward 44 px on each side. It never takes a
+  // neighbour's tap, and it writes 0 elsewhere. This layer takes taps out to
+  // there.
+  // SYNC: /packages/core/src/utils/hitArea.ts (HIT_INSET_PROPERTIES)
+  hitArea: {
+    '::after': {
+      content: '""',
+      position: 'absolute',
+      // Physical sides on purpose: the shared hit area measures each side
+      // from the page's rects, left and right included, in any direction.
+      inset:
+        'calc(var(--astryx-hit-inset-top, 0px) * -1) calc(var(--astryx-hit-inset-right, 0px) * -1) calc(var(--astryx-hit-inset-bottom, 0px) * -1) calc(var(--astryx-hit-inset-left, 0px) * -1)',
+    },
+  },
+});
+
+/**
+ * An info icon that reveals help: a small "i" button. Hover and keyboard
+ * focus preview the help. A click, tap, Enter, or Space pins it open until
+ * Escape, a second press, a press outside, or focus leaving. Use it next to
+ * labels, values, and metrics for permission notes, metric definitions, and
+ * field help.
+ *
+ * InfoTip is a press-to-pin Tooltip on a named button: Tooltip opens, pins,
+ * announces, and closes the help. The info icon resolves from
+ * the icon registry, so themes can replace it.
+ *
+ * @example
+ * ```
+ * <InfoTip content="Editors can change this field; viewers cannot." />
+ * <InfoTip content="30-day rolling average." label="About this metric" />
+ * ```
+ */
+export function InfoTip({
+  content,
+  label,
+  size = 'sm',
+  ref,
+  xstyle,
+  className,
+  style,
+}: InfoTipProps): ReactNode {
+  const t = useComponentTranslator();
+  // Under a coarse pointer the button takes taps out toward 44 px. The watch
+  // lives as long as the button is attached: the ref's cleanup stops it, and a
+  // replaced button starts its own.
+  const watchButtonHitArea = useCallback((button: HTMLButtonElement | null) => {
+    if (button == null) {
+      return;
+    }
+    return watchHitArea(button, insets => writeHitInsets(button, insets));
+  }, []);
+  const mergedRef = useMergedRefs(ref, watchButtonHitArea);
+
+  // No Escape handler of its own. Tooltip's entry in the shared dismissal
+  // stack takes Escape, so one press never closes both the help and an
+  // enclosing Dialog.
+  return (
+    <TooltipWithTriggerBehavior
+      content={content}
+      // The tooltip is the button's only purpose. A click, a tap, Enter, or
+      // Space pins it open, and the press stops at the button. So an InfoTip's
+      // content is reachable on a phone and from the keyboard alike.
+      triggerBehavior="toggle">
+      <button
+        ref={mergedRef}
+        type="button"
+        aria-label={label ?? t('@astryx.infoTip.label')}
+        {...mergeProps(
+          stylex.props(
+            focusOutlineStyles.focusVisible,
+            styles.trigger,
+            styles.hitArea,
+            xstyle,
+          ),
+          className,
+          style,
+        )}>
+        <Icon icon="info" size={size} />
+      </button>
+    </TooltipWithTriggerBehavior>
+  );
+}
+
+InfoTip.displayName = 'InfoTip';

package/src/InfoTip/index.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file InfoTip component barrel export
+ * @input InfoTip.tsx
+ * @output Exports InfoTip, InfoTipProps, InfoTipSize
+ * @position Barrel; consumed by packages/core/src/index.ts and the
+ *   `@astryxdesign/core/InfoTip` entry
+ */
+
+export {InfoTip} from './InfoTip';
+export type {InfoTipProps, InfoTipSize} from './InfoTip';

package/src/Layer/layerAnimations.stylex.ts

@@ -2,7 +2,8 @@
 
 /**
  * @file layerAnimations.stylex.ts
- * @input Uses StyleX, theme duration/easing tokens
+ * @input Uses StyleX, theme duration/easing tokens, the Reduce Motion fade
+ *   constants
  * @output Exports shared entry animation styles for layer-based components
  * @position Shared animation primitives; consumed by DropdownMenu, Popover,
  *   HoverCard, Tooltip, Selector, and any component using useLayer
@@ -27,6 +28,7 @@
  */
 
 import * as stylex from '@stylexjs/stylex';
+import {reducedMotionFadeConsts} from '../motion/reducedMotion.stylex';
 import {durationVars, easeVars, spacingVars} from '../theme/tokens.stylex';
 
 const enterBelow = stylex.keyframes({
@@ -84,17 +86,21 @@ const enterStartRtl = stylex.keyframes({
 
 // Reduce Motion under a finger: the same entrance without its travel. A touch
 // presentation substitutes a cross-fade for motion, never a jump.
+// The fade's curve rides in its first keyframe, so the published class type
+// of `animationTimingFunction` stays the theme ease's.
 const fadeIn = stylex.keyframes({
-  from: {opacity: 0},
+  from: {opacity: 0, animationTimingFunction: reducedMotionFadeConsts.easing},
   to: {opacity: 1},
 });
 
+// No theme value lengthens the Reduce Motion fade, so its values are constants.
+// The media keys stay literal: StyleX gives an imported at-rule key a later
+// priority layer (see reducedMotionKeys).
 const animationBase = {
   animationDuration: {
     default: durationVars['--duration-fast-max'],
-    // The cross-fade is 200 ms or less, whatever the theme's duration
-    // (design:reduced-motion DR2).
-    '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': `min(${durationVars['--duration-fast-max']}, 200ms)`,
+    '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
+      reducedMotionFadeConsts.duration,
   },
   animationTimingFunction: easeVars['--ease-standard'],
   animationFillMode: 'backwards' as const,
@@ -106,19 +112,18 @@ 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). Under a finger (the primary pointer is
- * coarse) it fades in instead, opacity only and in 200 ms or less: on a touch
- * screen Reduce Motion replaces motion with a cross-fade rather than a jump
- * (design:reduced-motion DR2, DR3), as iOS does for its menus, popovers and
- * tips.
+ * Under `prefers-reduced-motion: reduce` each entry drops its travel and
+ * scale. Under a finger (the primary pointer is coarse) the layer fades in,
+ * opacity only, in 200 ms on easeInOut: on a touch screen Reduce Motion
+ * replaces motion with a cross-fade rather than a jump; under any other
+ * pointer it appears at once.
  */
 export const layerAnimations = stylex.create({
   below: {
     animationName: {
       default: enterBelow,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
@@ -126,7 +131,8 @@ export const layerAnimations = stylex.create({
   above: {
     animationName: {
       default: enterAbove,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
@@ -135,7 +141,8 @@ export const layerAnimations = stylex.create({
     animationName: {
       default: enterEnd,
       ':is([dir="rtl"] *)': enterEndRtl,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,
@@ -144,7 +151,8 @@ export const layerAnimations = stylex.create({
     animationName: {
       default: enterStart,
       ':is([dir="rtl"] *)': enterStartRtl,
-      '@media (prefers-reduced-motion: reduce)': 'none',
+      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
+        'none',
       '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': fadeIn,
     },
     ...animationBase,

package/src/Layer/useBackdropPress.ts

@@ -0,0 +1,81 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useBackdropPress.ts
+ * @input A modal layer's backdrop dismissal and whether it is allowed now
+ * @output Capture-phase pointer handlers and a click handler for the layer's
+ *   <dialog> root
+ * @position Shared backdrop-press rule for Dialog and Drawer
+ */
+
+import {useCallback, useRef, type PointerEvent, type MouseEvent} from 'react';
+
+export interface BackdropPressHandlers {
+  onPointerDownCapture: (event: PointerEvent<HTMLElement>) => void;
+  onPointerUpCapture: (event: PointerEvent<HTMLElement>) => void;
+  onPointerCancelCapture: (event: PointerEvent<HTMLElement>) => void;
+  onClick: (event: MouseEvent<HTMLElement>) => void;
+}
+
+/**
+ * A press on a modal layer's backdrop targets the <dialog> root itself. A
+ * click there is also what the browser sends when a press starts on one side
+ * of the layer's edge and ends on the other (it goes to the nearest common
+ * ancestor), so a backdrop press dismisses only when its pointer-down and its
+ * pointer-up both landed on the backdrop. A cancelled pointer ends the press.
+ *
+ * The pointer handlers run in the capture phase. A nested layer, such as a
+ * popover open in the dialog, stops its presses at its own root, so a
+ * bubble-phase handler here does not see them.
+ */
+export function useBackdropPress(
+  onBackdropPress: () => void,
+  isEnabled: boolean,
+): BackdropPressHandlers {
+  const startedOnBackdropRef = useRef(false);
+  const endedOnBackdropRef = useRef(false);
+
+  const onPointerDownCapture = useCallback(
+    (event: PointerEvent<HTMLElement>) => {
+      startedOnBackdropRef.current = event.target === event.currentTarget;
+      endedOnBackdropRef.current = false;
+    },
+    [],
+  );
+
+  const onPointerUpCapture = useCallback((event: PointerEvent<HTMLElement>) => {
+    endedOnBackdropRef.current =
+      startedOnBackdropRef.current && event.target === event.currentTarget;
+    startedOnBackdropRef.current = false;
+  }, []);
+
+  const onPointerCancelCapture = useCallback(() => {
+    startedOnBackdropRef.current = false;
+    endedOnBackdropRef.current = false;
+  }, []);
+
+  const onClick = useCallback(
+    (event: MouseEvent<HTMLElement>) => {
+      const pressWasOnBackdrop = endedOnBackdropRef.current;
+      startedOnBackdropRef.current = false;
+      endedOnBackdropRef.current = false;
+      if (
+        isEnabled &&
+        pressWasOnBackdrop &&
+        event.target === event.currentTarget
+      ) {
+        onBackdropPress();
+      }
+    },
+    [isEnabled, onBackdropPress],
+  );
+
+  return {
+    onPointerDownCapture,
+    onPointerUpCapture,
+    onPointerCancelCapture,
+    onClick,
+  };
+}