@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/src/InputGroup/InputGroup.tsx

@@ -109,7 +109,8 @@ export interface InputGroupProps extends Omit<
   size?: InputGroupSize;
 
   /**
-   * Status indicator applied to the group border.
+   * Validation status. Its message shows below the group. The group border
+   * does not change; a theme can style the row from `data-status`.
    */
   status?: InputStatus;
 
@@ -125,8 +126,8 @@ export interface InputGroupProps extends Omit<
 }
 
 /**
- * Groups an input with prefix/suffix addons in a visually connected
- * container with shared border and focus ring.
+ * Groups an input with prefix and suffix addons in one connected row. A
+ * focused member stays above its neighbours, so its focus ring shows in full.
  *
  * @example
  * ```

package/src/InputGroup/InputGroupText.doc.mjs

@@ -7,7 +7,42 @@ export const docs = {
   subComponentOf: 'InputGroup',
   displayName: 'Input Group Text',
   isHiddenFromOverview: true,
-  description: 'A prefix or suffix text element rendered inside InputGroup. Displays text or icons.',
+  description:
+    'A prefix or suffix text element rendered inside InputGroup. Displays text or icons.',
+  usage: {
+    description:
+      "Use InputGroupText inside InputGroup for a short fixed prefix or suffix, such as a currency symbol, a protocol, or a unit, or for a decorative icon. It is plain text, not a control, and it is not part of the input's accessible name.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Keep the text short, such as $, https://, or kg. It stays on one line and does not shrink.',
+      },
+      {
+        guidance: true,
+        description:
+          'Put what a screen reader user needs in the input\'s own label, such as "Amount in USD" beside a $ prefix. The addon is read as plain text in reading order.',
+      },
+      {
+        guidance: false,
+        description:
+          'Put buttons, links, or other controls inside InputGroupText. Use a Button addon for an action.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use InputGroupText outside InputGroup. Its borders and corners join an InputGroup row.',
+      },
+    ],
+    anatomy: [
+      {
+        name: 'Text cell',
+        required: true,
+        description:
+          'A non-interactive cell that holds text or an icon and joins the borders of its neighbours in the row.',
+      },
+    ],
+  },
   props: [
     {
       name: 'children',
@@ -18,7 +53,8 @@ export const docs = {
     {
       name: 'xstyle',
       type: 'StyleXStyles',
-      description: 'StyleX styles for customization.',
+      description:
+        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
     },
     {
       name: 'className',
@@ -30,6 +66,11 @@ export const docs = {
       type: 'React.CSSProperties',
       description: 'Inline styles.',
     },
+    {
+      name: 'ref',
+      type: 'React.Ref<HTMLDivElement>',
+      description: 'Ref forwarded to the text cell element.',
+    },
   ],
 };
 
@@ -40,8 +81,9 @@ export const docsDense = {
   description: 'prefix/suffix text/icon element',
   propDescriptions: {
     children: 'text or icon content',
-    xstyle: 'StyleX styles',
+    xstyle: 'StyleX styles (stylex.create() value)',
     className: 'CSS class name(s)',
     style: 'inline styles',
+    ref: 'ref to the text cell',
   },
 };

package/src/InputGroup/InputGroupText.tsx

@@ -10,6 +10,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/InputGroup/InputGroup.doc.mjs
+ * - /packages/core/src/InputGroup/InputGroupText.doc.mjs
  * - /packages/core/src/InputGroup/index.ts
  * - /packages/cli/assets/templates/blocks/components/InputGroup/
  */
@@ -81,7 +82,7 @@ export interface InputGroupTextProps extends BaseProps<HTMLDivElement> {
  *
  * @example
  * ```
- * <InputGroup label="URL">
+ * <InputGroup label="Website">
  *   <InputGroupText>https://</InputGroupText>
  *   <TextInput label="URL" isLabelHidden value={url} onChange={setUrl} />
  * </InputGroup>

package/src/InputGroup/groupStyles.ts

@@ -96,8 +96,10 @@ export const groupStyles = stylex.create({
       default: 0,
       [IS_LAST_ITEM]: radiusVars['--radius-element'],
     },
+    // Input wrappers already sit at z-index 1. A focused member goes one
+    // higher, so an unfocused input beside it cannot cover its focus ring.
     ':focus-within': {
-      zIndex: 1,
+      zIndex: 2,
     },
   },
 });

package/src/Item/Item.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file Item.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens, useClickableContainer
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, useClickableContainer,
+ *   the shared press overlays and the compositor press layer
  * @output Exports Item component, ItemProps type; publishes the shared inline inset.
  *   Only numbered composing rows keep their start/label/end slots in one flex
  *   group, through Item's private exact-marker scope; other marked rows keep
@@ -50,17 +51,25 @@ import {
 import type {BaseProps} from '../BaseProps';
 import {isRenderable} from '../utils/isRenderable';
 import {mergeProps} from '../utils/mergeProps';
+import {chainEventHandlers} from '../utils/chainEventHandlers';
 import {useFocusAcrossSwap} from '../utils/useFocusAcrossSwap';
 import {ItemDescriptionContext} from './ItemDescriptionContext';
+import {ItemListRowContext} from './ItemListRowContext';
 import {ItemMarkerColumnsContext} from './ItemMarkerColumnsContext';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {computeTargetAndRel} from '../Link/computeTargetAndRel';
 import {useLinkComponent} from '../Link/useLinkComponent';
-import {useClickableContainer} from '../hooks/useClickableContainer';
+import {
+  cancelNestedTouchPress,
+  PRESSABLE_CONTAINER_ATTRIBUTE,
+  useClickableContainerProxy,
+} from '../hooks/useClickableContainer';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
+import {rowPressLayerStyles} from '../privateAttributes/press.stylex';
+import {isCoarsePointer} from '../utils/coarsePointer';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import type {ItemSwipeBridge} from './ItemSwipeLayer';
 
@@ -334,6 +343,41 @@ const ARIA_SELECTED_ROLES = new Set([
  */
 const SWIPE_ROLES = new Set(['listitem']);
 
+/**
+ * Whether a row serves swipe actions, and so is a stacking context at rest:
+ * its root translates (`styles.swipeRoot`). Swipe actions need a
+ * role that permits interactive descendants, since a swipe panel holds
+ * buttons. That is a `listitem`, or no role at all. A root that is itself a
+ * link is not served, nor is a role that forbids interactive descendants. A
+ * disabled row, a row with no entry on either side, and the enlarged target of
+ * a nested control are not served either. Internal: under a finger,
+ * List/ListItem.tsx raises such a row, so its touch band stays above the rows
+ * after it.
+ */
+export function servesSwipeActions({
+  swipeActions,
+  isDisabled,
+  isDelegate,
+  isLinkRoot,
+  role,
+}: {
+  readonly swipeActions: ItemSwipeActions | undefined;
+  readonly isDisabled: boolean;
+  readonly isDelegate: boolean;
+  readonly isLinkRoot: boolean;
+  readonly role: string | null | undefined;
+}): boolean {
+  return (
+    swipeActions != null &&
+    ((swipeActions.leading?.length ?? 0) > 0 ||
+      (swipeActions.trailing?.length ?? 0) > 0) &&
+    !isDisabled &&
+    !isDelegate &&
+    !isLinkRoot &&
+    (role == null || SWIPE_ROLES.has(role))
+  );
+}
+
 /** The travel a drag writes on the row root, in physical px (see useSwipeAction). */
 const SWIPE_TRAVEL = 'var(--_item-swipe-travel, 0px)';
 /** The settle clock, `0s` while the finger drives the row. */
@@ -532,7 +576,6 @@ const styles = stylex.create({
   // zoomable (WCAG 1.4.4). The hover transition keeps its own clock beside
   // the transform's.
   swipeRoot: {
-    isolation: 'isolate',
     touchAction: 'pan-y pinch-zoom',
     transform: `translate3d(${SWIPE_TRAVEL}, 0, 0)`,
     transitionProperty: 'background-color, transform',
@@ -611,6 +654,7 @@ export function Item({
 }: ItemProps) {
   const pressable = usePressFeedback();
   const columnMarker = use(ItemMarkerColumnsContext);
+  const isListRow = use(ItemListRowContext);
   const LinkComponent = useLinkComponent();
   // A disabled row's anchor has no destination, so no activation path (a
   // screen reader's click, Enter, a link context menu) can navigate
@@ -618,7 +662,11 @@ export function Item({
   // the router link component, which may require a live href. The element type
   // then changes with `isDisabled`, so focus follows the swap (FR4).
   const RowAnchor = isDisabled ? 'a' : LinkComponent;
-  const anchorRef = useFocusAcrossSwap<HTMLAnchorElement>();
+  // The row's own action, its invisible link or button: a press on it
+  // activates the row.
+  const actionLinkRef = useRef<HTMLAnchorElement | null>(null);
+  const actionButtonRef = useRef<HTMLButtonElement | null>(null);
+  const anchorRef = useFocusAcrossSwap<HTMLAnchorElement>(actionLinkRef);
 
   // Delegation mode: the row is an enlarged click/tap target for a nested
   // control (e.g. a checkbox) that owns the keyboard access and action. The
@@ -626,12 +674,14 @@ export function Item({
   const isDelegate = interactiveRef != null;
   const containerRef = useRef<HTMLElement | null>(null);
   // Only onClick is needed: onMouseUp handles middle-click href navigation,
-  // which delegation mode never has (href is ignored here).
-  const {onClick: delegatedOnClick} = useClickableContainer({
-    containerRef,
-    interactiveRef: interactiveRef ?? undefined,
-    disabled: isDisabled,
-  });
+  // which delegation mode never has (href is ignored here). A List link row's
+  // surface click goes to its anchor through the same hook and its guards.
+  const {onClick: containerOnClick, onPointerDown: delegatedOnPointerDown} =
+    useClickableContainerProxy({
+      containerRef,
+      interactiveRef: interactiveRef ?? actionLinkRef,
+      disabled: isDisabled,
+    });
 
   useDevWarning(
     'Item',
@@ -651,20 +701,28 @@ export function Item({
   // component means the root itself is the anchor, so the address rides it
   // and the invisible anchor below is not rendered.
   const isLinkRoot = typeof Component !== 'string' && href != null;
+  // A press on a nested control does not run this row's action, so the row
+  // shows no touch press. A row with a parent role or a link root runs it, so
+  // it keeps the press. Such a row is not a clickable container: an enclosing
+  // card still treats it as part of its own surface.
+  const hasOwnAction =
+    (onClick != null || href != null) && !hasParentRole && !isLinkRoot;
+  const pressOnRow = (event: React.PointerEvent<HTMLElement>) =>
+    cancelNestedTouchPress(
+      event,
+      event.currentTarget,
+      href != null ? actionLinkRef.current : actionButtonRef.current,
+    );
 
-  // Swipe actions exist where the row's role permits interactive descendants
-  // (a swipe panel's buttons are such descendants): a `listitem`, or no role
-  // at all. A root that is itself a link, a row whose role forbids them, and
-  // a row that is the enlarged target of a nested control are not served.
   const leadingSwipe = swipeActions?.leading ?? [];
   const trailingSwipe = swipeActions?.trailing ?? [];
-  const hasSwipe =
-    swipeActions != null &&
-    (leadingSwipe.length > 0 || trailingSwipe.length > 0) &&
-    !isDisabled &&
-    !isDelegate &&
-    !isLinkRoot &&
-    (role == null || SWIPE_ROLES.has(role));
+  const hasSwipe = servesSwipeActions({
+    swipeActions,
+    isDisabled,
+    isDelegate,
+    isLinkRoot,
+    role,
+  });
   useDevWarning(
     'Item',
     '`swipeBehavior="commit"` fires only the outermost entry of a side; the ' +
@@ -759,6 +817,8 @@ export function Item({
     </>
   );
 
+  const isLinkRow = isListRow && onClick == null && href != null && !isLinkRoot;
+
   const handleContainerClick = (e: React.MouseEvent) => {
     if (isDisabled) {
       return;
@@ -767,6 +827,25 @@ export function Item({
     if (target.closest('button, a, input, select, textarea')) {
       return;
     }
+    if (isLinkRow) {
+      // Under a coarse primary pointer, a tap in the row's padding or band
+      // follows its link, with the click's modifier keys. The primary pointer
+      // decides, as it decides the band, not the pointer that made the click.
+      const row = e.currentTarget as HTMLElement;
+      const box = row.getBoundingClientRect();
+      const isInBand =
+        e.clientX < box.left ||
+        e.clientX > box.right ||
+        e.clientY < box.top ||
+        e.clientY > box.bottom;
+      if (
+        e.detail > 0 &&
+        (isInBand || isCoarsePointer(row.ownerDocument.defaultView))
+      ) {
+        containerOnClick(e as React.MouseEvent<HTMLElement>);
+      }
+      return;
+    }
     onClick?.(e);
   };
 
@@ -809,6 +888,7 @@ export function Item({
         </RowAnchor>
       ) : onClick != null ? (
         <button
+          ref={actionButtonRef}
           type="button"
           onClick={onClick}
           disabled={isDisabled}
@@ -845,14 +925,14 @@ export function Item({
 
   const mergedRef = useMergedRefs(ref, containerRef);
   const rootRef = useMergedRefs(
-    (isDelegate ? mergedRef : ref) as React.Ref<HTMLElement>,
+    (isDelegate || isLinkRow ? mergedRef : ref) as React.Ref<HTMLElement>,
     hasSwipe ? swipeRootRef : undefined,
   );
 
   // The row's own primary, which the click the browser synthesizes after a
   // drag must not fire.
   const primaryOnClick = isDelegate
-    ? delegatedOnClick
+    ? containerOnClick
     : hasParentRole
       ? onClick
       : isInteractive
@@ -896,6 +976,24 @@ export function Item({
       {...restProps}
       {...swipeHandlers}
       {...linkRootProps}
+      {...(isDelegate
+        ? {
+            onPointerDown: chainEventHandlers(
+              restProps.onPointerDown,
+              delegatedOnPointerDown,
+            ),
+          }
+        : hasOwnAction && !isDisabled
+          ? {
+              onPointerDown: chainEventHandlers(
+                swipeHandlers?.onPointerDown ?? restProps.onPointerDown,
+                pressOnRow,
+              ),
+            }
+          : null)}
+      // Only a delegate row is a pressable container. So a mouse click in a
+      // link row's padding still reaches a clickable container around it.
+      {...(isDelegate ? {[PRESSABLE_CONTAINER_ATTRIBUTE]: 'true'} : undefined)}
       aria-selected={(allowsAriaSelected && isSelected) || undefined}
       // aria-selected is invalid on roles that don't permit it (listitem, a
       // bare div, etc.). For those, convey selection via aria-current — valid
@@ -916,6 +1014,10 @@ export function Item({
           align === 'first-line' && styles.alignFirstLine,
           isInteractive && styles.interactive,
           isInteractive && interactionOverlayStyles.backgroundColor,
+          // The touch press on a compositor layer (after the overlay, whose
+          // own touch paint it turns off): the release keeps fading while
+          // script runs.
+          isInteractive && rowPressLayerStyles.cell,
           isLinkRoot && styles.linkRoot,
           isHighlighted && styles.highlighted,
           isSelected && styles.selected,
@@ -930,18 +1032,20 @@ export function Item({
       onClick={rootOnClick}>
       <ItemDescriptionContext
         value={hasRenderableDescription ? descriptionID : null}>
-        {isRenderable(marker) && marker}
-        {isRenderable(marker) && columnMarker === marker ? (
-          <span
-            {...stylex.props(
-              styles.markerContent,
-              align === 'first-line' && styles.markerContentFirstLine,
-            )}>
-            {content}
-          </span>
-        ) : (
-          content
-        )}
+        <ItemListRowContext value={false}>
+          {isRenderable(marker) && marker}
+          {isRenderable(marker) && columnMarker === marker ? (
+            <span
+              {...stylex.props(
+                styles.markerContent,
+                align === 'first-line' && styles.markerContentFirstLine,
+              )}>
+              {content}
+            </span>
+          ) : (
+            content
+          )}
+        </ItemListRowContext>
       </ItemDescriptionContext>
       {hasSwipe && (
         // The panels: out-of-flow children of this root, so the DOM is the one

package/src/Item/ItemListRowContext.tsx

@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ItemListRowContext.tsx
+ * @input Uses React createContext
+ * @output Exports ItemListRowContext
+ * @position Internal seam between ListItem and the Item it renders. Under a
+ *   coarse primary pointer a List row's whole touch target follows its link,
+ *   so ListItem marks its Item as a List row. Item clears the mark for its own
+ *   content, and a standalone Item has none.
+ */
+
+import {createContext} from 'react';
+
+export const ItemListRowContext = createContext(false);
+ItemListRowContext.displayName = 'ItemListRowContext';

package/src/Layer/holdEntranceInput.ts

@@ -0,0 +1,84 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file holdEntranceInput.ts
+ * @input A layer root whose CSS entrance has just started
+ * @output holdEntranceInput: under a coarse primary pointer, a finger's or a
+ *   pen's input held away from the layer until its entrance ends
+ * @position The entrance hold for layers that enter through CSS (Dialog,
+ *   Drawer, MobileNav), on the Layer module's input hold (inputHold.ts)
+ *
+ * SYNC: When modified, update holdEntranceInput.test.ts and its callers
+ * (Dialog.tsx, Drawer/useDrawerDialogPresence.ts, MobileNav/MobileNav.tsx).
+ */
+
+import {isCoarsePointer} from '../utils/coarsePointer';
+import {holdInput} from './inputHold';
+
+/** Options for {@link holdEntranceInput}. */
+export interface EntranceHoldOptions {
+  /**
+   * Holds input anywhere while true. While false, only what lands on the layer
+   * is held, and the page stays live.
+   * @default true
+   */
+  isModal?: boolean;
+  /**
+   * The element whose animations are the entrance, when it is not the layer
+   * itself (a drawer inside its dialog).
+   * @default the layer
+   */
+  entrance?: Element | null;
+  /** The longest the hold lasts, ms. An entrance that runs longer ends it. */
+  capMs?: number;
+}
+
+/**
+ * Holds a finger's and a pen's input away from `layer` until its entrance
+ * ends, or at most `capMs`. Returns the release, or `null` when nothing is
+ * held: no entrance runs, or the primary pointer is fine.
+ */
+export function holdEntranceInput(
+  layer: Element,
+  {isModal = true, entrance: animated = layer, capMs}: EntranceHoldOptions = {},
+): (() => void) | null {
+  if (animated == null || typeof animated.getAnimations !== 'function') {
+    return null;
+  }
+  // getAnimations() flushes styles, so it lists an entrance the open has just
+  // started. A theme's duration, a shorter reduced-motion entrance and a
+  // canceled entrance all end the hold when they end.
+  const entrance = animated.getAnimations().filter(isEntrance);
+  if (entrance.length === 0) {
+    return null;
+  }
+  // A touch presentation only, read as the layer opens. A finger on a device
+  // whose primary pointer is fine, such as a touchscreen laptop, is not held.
+  if (!isCoarsePointer(layer.ownerDocument.defaultView)) {
+    return null;
+  }
+  const ended = Promise.all(
+    entrance.map(async animation => animation.finished),
+  );
+  return holdInput(layer, {
+    until: capMs == null ? ended : Promise.race([ended, after(capMs)]),
+    scope: isModal ? 'viewport' : 'surface',
+  });
+}
+
+async function after(ms: number): Promise<void> {
+  await new Promise(resolve => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/** A running animation that ends on its own: an entrance, not a spin. */
+function isEntrance(animation: Animation): boolean {
+  if (animation.playState !== 'running') {
+    return false;
+  }
+  const end = animation.effect?.getComputedTiming().endTime;
+  return typeof end === 'number' && Number.isFinite(end);
+}