@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/IconButton/IconButton.doc.mjs

@@ -20,7 +20,8 @@ export const docs = {
     {
       name: 'icon',
       type: 'ReactNode',
-      description: 'Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
+      description:
+        'Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
       required: true,
       slotElements: [{__element: 'Icon', props: {icon: 'check'}}],
     },
@@ -46,19 +47,22 @@ export const docs = {
     {
       name: 'isLoading',
       type: 'boolean',
-      description: 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
+      description:
+        'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
       default: 'false',
     },
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Disables the button.',
+      description:
+        'Disables the button. When a tooltip is present, uses aria-disabled instead of native disabled so the button stays focusable.',
       default: 'false',
     },
     {
       name: 'tooltip',
       type: 'string',
-      description: 'Tooltip text shown on hover.',
+      description:
+        "Tooltip text shown on hover and keyboard focus. It also describes the button, unless it repeats the button's accessible name.",
     },
     {
       name: 'onClick',
@@ -70,10 +74,69 @@ export const docs = {
       type: '(e: MouseEvent) => void | Promise<void>',
       description: 'Async click handler with automatic loading state.',
     },
+    {
+      name: 'isInterruptible',
+      type: 'boolean',
+      description:
+        'Keep the button clickable while a clickAction is pending: the spinner and aria-busy still show, but the button is not disabled and the action is not deduped, so a re-click lands and interrupts the in-flight action with a fresh one. Use it for interruptible actions, not fire-once actions (submit, save, pay).',
+      default: 'false',
+    },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the button. Numbers are treated as pixels, strings are used as-is. Without it the button keeps its icon-only aspect, square by default; with it the button takes that width.',
+    },
+    {
+      name: 'type',
+      type: "'button' | 'submit' | 'reset'",
+      description: 'HTML button type attribute.',
+      default: "'button'",
+    },
+    {
+      name: 'name',
+      type: 'string',
+      description: 'HTML name attribute for form submission.',
+    },
+    {
+      name: 'value',
+      type: 'string | number | readonly string[]',
+      description: 'HTML value attribute for form submission.',
+    },
+    {
+      name: 'form',
+      type: 'string',
+      description: 'Associates the button with a form element by ID.',
+    },
+    {
+      name: 'href',
+      type: 'string',
+      description:
+        'When provided, renders the button as a link element (<a> or custom link component). A disabled IconButton still renders a <button>.',
+    },
+    {
+      name: 'as',
+      type: 'ComponentType',
+      description:
+        'Custom link component to use when href is provided (e.g. Next.js Link).',
+    },
+    {
+      name: 'target',
+      type: 'string',
+      description:
+        'HTML target attribute when rendered as a link (e.g. "_blank").',
+    },
+    {
+      name: 'rel',
+      type: 'string',
+      description:
+        'HTML rel attribute when rendered as a link (e.g. "noopener noreferrer").',
+    },
   ],
 
   usage: {
-    description: 'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
+    description:
+      'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
     accessibility: [
       {
         name: 'Essential icon or spinner arc',
@@ -113,26 +176,68 @@ export const docs = {
       },
     ],
     bestPractices: [
-      { guidance: true, description: 'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.' },
-      { guidance: true, description: 'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.' },
-      { guidance: true, description: 'Use ghost in toolbars and dense areas to reduce visual clutter.' },
-      { guidance: false, description: 'Use IconButton if the action isn\'t obvious from the icon alone; use Button with text.' },
-      { guidance: false, description: 'Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.' },
+      {
+        guidance: true,
+        description:
+          'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use ghost in toolbars and dense areas to reduce visual clutter.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use IconButton if the action isn't obvious from the icon alone; use Button with text.",
+      },
+      {
+        guidance: false,
+        description:
+          'Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.',
+      },
     ],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
+  description:
+    'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
   usage: {
-    description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
+    description:
+      'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
     bestPractices: [
-      { guidance: true, description: 'Make aria-label specific: trash icon labeled "Delete conversation" > just "Delete" for screen readers.' },
-      { guidance: true, description: 'Add tooltip: even gear icon can mean Settings/Preferences/Configure.' },
-      { guidance: true, description: 'Use ghost in toolbars + dense areas to reduce visual clutter.' },
-      { guidance: false, description: "Use IconButton if action isn't obvious from icon alone; use Button w/ text instead." },
-      { guidance: false, description: 'Skip tooltip: label only reaches screen readers; sighted users need hover hint.' },
+      {
+        guidance: true,
+        description:
+          'Make aria-label specific: trash icon labeled "Delete conversation" > just "Delete" for screen readers.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add tooltip: even gear icon can mean Settings/Preferences/Configure.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use ghost in toolbars + dense areas to reduce visual clutter.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use IconButton if action isn't obvious from icon alone; use Button w/ text instead.",
+      },
+      {
+        guidance: false,
+        description:
+          'Skip tooltip: label only reaches screen readers; sighted users need hover hint.',
+      },
     ],
   },
   propDescriptions: {
@@ -140,11 +245,26 @@ export const docsDense = {
     icon: 'icon element rendered inside button; unsized Astryx Icon defaults to sm for sm/md buttons and md for lg',
     variant: 'visual style variant',
     size: 'size variant',
-    elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
-    isLoading: 'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
-    isDisabled: 'disables button',
-    tooltip: 'tooltip text shown on hover',
+    elevation:
+      'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
+    isLoading:
+      'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
+    isDisabled: 'disables button; uses aria-disabled when tooltip present',
+    tooltip:
+      'tooltip on hover + keyboard focus; also describes the button unless it repeats the accessible name',
     onClick: 'standard click handler',
     clickAction: 'async click handler w/ automatic loading state',
+    isInterruptible:
+      'keeps button clickable while clickAction pending; a re-click interrupts it. Not for fire-once actions (submit/save/pay)',
+    width:
+      'button width; numbers=pixels, strings=as-is; without it keeps the icon-only aspect (square by default)',
+    type: 'HTML button type; defaults to "button"',
+    name: 'HTML name for form submission',
+    value: 'HTML value for form submission',
+    form: 'associates button with form element by ID',
+    href: 'renders as a link; a disabled IconButton stays a <button>',
+    as: 'custom link component used with href',
+    target: 'HTML target when rendered as a link',
+    rel: 'HTML rel when rendered as a link',
   },
 };

package/src/InfoTip/InfoTip.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file InfoTip.tsx
- * @input Uses React, StyleX, Tooltip, Icon, useComponentTranslator, the shared
- *   touch hit area, color/spacing/radius/duration/ease tokens
+ * @input Uses React, StyleX, useTooltip, 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
@@ -17,13 +17,21 @@
  * - /packages/core/src/InfoTip/index.ts (exports if types change)
  */
 
-import {useCallback, type ReactNode, type Ref} from 'react';
+import {
+  useCallback,
+  useState,
+  type MouseEvent,
+  type PointerEvent,
+  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 {stopInReactTree} from '../Layer/layerClickBoundary';
+import {useTooltip} from '../Tooltip/useTooltip';
 import {
   registerEnglishFallback,
   useComponentTranslator,
@@ -122,9 +130,9 @@ const styles = stylex.create({
  * 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.
+ * InfoTip is a named button that toggles `useTooltip`'s `show()` and `hide()`:
+ * the hook previews, holds, announces, and closes the help. The info icon
+ * resolves from the icon registry, so themes can replace it.
  *
  * @example
  * ```
@@ -151,22 +159,69 @@ export function InfoTip({
     }
     return watchHitArea(button, insets => writeHitInsets(button, insets));
   }, []);
-  const mergedRef = useMergedRefs(ref, watchButtonHitArea);
+  // Whether a press pinned the help. A hover or focus preview is not pinned.
+  const [isPinned, setIsPinned] = useState(false);
+  // Whether the help shows, pinned or previewed: the button names it in
+  // `aria-controls` only then.
+  const [isShown, setIsShown] = useState(false);
+  const handleShow = useCallback(() => setIsShown(true), []);
+  // Every close ends the pin: a second press, Escape, a press outside, or
+  // focus leaving.
+  const handleHide = useCallback(() => {
+    setIsShown(false);
+    setIsPinned(false);
+  }, []);
+  const tooltip = useTooltip({onShow: handleShow, onHide: handleHide});
+  const mergedRef = useMergedRefs(ref, watchButtonHitArea, tooltip.ref);
+
+  // A primary mouse or pen press on a preview calls show() first. The hook's
+  // press-to-close then leaves it open. The click pins it.
+  const handlePointerDownCapture = useCallback(
+    (event: PointerEvent<HTMLButtonElement>) => {
+      if (
+        event.button !== 0 ||
+        event.pointerType === 'touch' ||
+        isPinned ||
+        !isShown
+      ) {
+        return;
+      }
+      tooltip.show();
+    },
+    [isPinned, isShown, tooltip],
+  );
+
+  // A click, tap, Enter, or Space pins the help, and the next one closes it.
+  // The press stops at the button: a clickable row, card, or label around it
+  // does nothing, and document listeners still see it.
+  const handleClick = useCallback(
+    (event: MouseEvent<HTMLButtonElement>) => {
+      stopInReactTree(event);
+      event.preventDefault();
+      if (isPinned) {
+        tooltip.hide();
+        return;
+      }
+      tooltip.show();
+      setIsPinned(true);
+    },
+    [isPinned, tooltip],
+  );
 
-  // No Escape handler of its own. Tooltip's entry in the shared dismissal
+  // No Escape handler of its own. The 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')}
+        aria-describedby={tooltip.describedBy}
+        aria-expanded={isPinned}
+        aria-controls={isShown ? tooltip.describedBy : undefined}
+        onPointerDownCapture={handlePointerDownCapture}
+        onClick={handleClick}
         {...mergeProps(
           stylex.props(
             focusOutlineStyles.focusVisible,
@@ -179,7 +234,8 @@ export function InfoTip({
         )}>
         <Icon icon="info" size={size} />
       </button>
-    </TooltipWithTriggerBehavior>
+      {tooltip.renderTooltip(content)}
+    </>
   );
 }
 

package/src/Item/useSwipeAction.ts

@@ -237,6 +237,8 @@ export function useSwipeAction({
     reducedMotionRef.current = isReducedMotion;
   });
 
+  // Releases the settle timer, the animation frame and the pinch watch on
+  // unmount.
   useEffect(
     () => () => {
       if (settleTimerRef.current != null) {

package/src/Layer/modalOutlet.ts

@@ -188,6 +188,8 @@ export function useModalOutlet(
   const isLatestRef = useRef(isLatest);
   isLatestRef.current = isLatest;
   const suppliedRef = useRef<HTMLDialogElement | null>(null);
+  // Syncs the module registry of modal outlets with this dialog while it is
+  // active. It also follows the dialog's native `close` event.
   useEffect(() => {
     const element = ref.current;
     if (!isActive || element == null) {

package/src/Layer/outsidePress.ts

@@ -96,6 +96,7 @@ export function useOutsidePress(): OutsidePressWatch {
     },
     [],
   );
+  // Stops the outside-press listeners on unmount.
   useEffect(() => stop, [stop]);
   return useMemo(() => ({start, stop}), [start, stop]);
 }

package/src/Layer/useLayer.tsx

@@ -57,7 +57,7 @@ import {
 import {preserveAnimations} from './preserveAnimations';
 import {useLayerContext} from './LayerContext';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
-import {overlayPaddingReset} from '../Layout/padding.stylex';
+import {overlayPaddingReset} from '../Layout/overlayPaddingReset.stylex';
 
 const styles = stylex.create({
   // Base reset for all layers
@@ -1560,6 +1560,8 @@ function useLayerImplementation(
     forgetDismissalRef.current = forget;
   }, []);
 
+  // Syncs the document's capture-phase gesture tracking with this mount.
+  // Unmount forgets the layer's dismissal.
   useEffect(() => {
     // Install capture-phase gesture tracking before the first interaction.
     currentGesture();

package/src/Layer/useLayerDismissal.ts

@@ -155,6 +155,8 @@ export function useLayerDismissal(
 
   const isRegistered = isActive && isEnabled;
 
+  // Syncs the shared dismissal stack with `isRegistered`. A registered layer
+  // gets Escape and outside presses in stack order.
   useEffect(() => {
     if (!isRegistered) {
       wasRegisteredRef.current = false;

package/src/Layer/useTouchTrigger.ts

@@ -8,7 +8,7 @@
  * @output Exports useTouchTrigger hook, isActionTrigger, LayerTouchTrigger type,
  *   tapLandsOnDisabledControl, TOUCH_POINTER_TYPES and useTapStop (internal:
  *   not re-exported from index). Also useTouchTriggerInternal, with the
- *   outside dismissal's arm for the press pin (Core-internal).
+ *   outside dismissal's arm for useTooltip's hold (Core-internal).
  * @position Layer hook; shared touch behavior for useTooltip and useHoverCard
  *
  * SYNC: When modified, update:
@@ -283,8 +283,8 @@ export interface UseTouchTriggerReturn {
 }
 
 /**
- * useTouchTrigger's return plus the outside dismissal's arm, for Core's own
- * press pin (usePressPin). Not exported from the Layer entry point.
+ * useTouchTrigger's return plus the outside dismissal's arm, for useTooltip's
+ * hold behind show() and hide(). Not exported from the Layer entry point.
  *
  * @internal
  */
@@ -292,7 +292,7 @@ export interface UseTouchTriggerInternalReturn extends UseTouchTriggerReturn {
   /**
    * Arms the outside dismissal a tap-open gets: a press that lifts outside
    * the trigger and the layer, or a scroll that starts there, hides it. A
-   * press pin arms it too.
+   * hold arms it too.
    */
   armOutsideDismiss: () => void;
 }
@@ -328,13 +328,19 @@ export function useTouchTrigger(
 }
 
 /**
- * useTouchTrigger, plus the outside dismissal's arm that a press pin uses to
- * close on a press or scroll outside.
+ * useTouchTrigger, plus the outside dismissal's arm that useTooltip's hold
+ * uses to close on a press or scroll outside.
  *
  * @internal
  */
 export function useTouchTriggerInternal(
   options: UseTouchTriggerOptions,
+  /**
+   * Called when a press that the outside dismissal watches ends with its
+   * pointer lifted inside the layer: the layer stays open, and useTooltip
+   * ends a hold that the press started.
+   */
+  onReleaseInLayer?: () => void,
 ): UseTouchTriggerInternalReturn {
   const {
     touchTrigger,
@@ -359,6 +365,8 @@ export function useTouchTriggerInternal(
   hideRef.current = hide;
   const layerIdRef = useRef(layerId);
   layerIdRef.current = layerId;
+  const onReleaseInLayerRef = useRef(onReleaseInLayer);
+  onReleaseInLayerRef.current = onReleaseInLayer;
 
   // Whether a tap is what opened the layer. Only a tap-open owes the user an
   // outside-tap dismissal: a hover-opened layer already closes on
@@ -421,6 +429,9 @@ export function useTouchTriggerInternal(
               doc.getElementById(layerIdRef.current)?.contains(target) === true,
           )
         ) {
+          if (event.type === 'pointerup') {
+            onReleaseInLayerRef.current?.();
+          }
           return;
         }
       }
@@ -436,7 +447,9 @@ export function useTouchTriggerInternal(
     }
   }, [triggerRef, disarmOutsideDismiss]);
 
+  // Releases the outside-dismiss listener on unmount.
   useEffect(() => disarmOutsideDismiss, [disarmOutsideDismiss]);
+  // Releases a pending tap on unmount.
   useEffect(() => () => forgetPendingTapRef.current?.(), []);
 
   const isTouchInteraction = useCallback(

package/src/Layout/index.ts

@@ -21,7 +21,7 @@ export type {
 
 // Overlay padding-variable reset (applied on overlay roots so the container
 // padding system does not cross a fixed/top-layer boundary)
-export {overlayPaddingReset} from './padding.stylex';
+export {overlayPaddingReset} from './overlayPaddingReset.stylex';
 
 // Edge compensation utility
 export {edgeCompSlot, EDGE_COMP_ATTR} from './edgeCompensation.stylex';

package/src/Layout/layoutReset.ts

@@ -18,7 +18,7 @@
  */
 
 import * as stylex from '@stylexjs/stylex';
-import {overlayPaddingReset} from './padding.stylex';
+import {overlayPaddingReset} from './overlayPaddingReset.stylex';
 
 const resetBeyondOverlays = stylex.create({
   root: {

package/src/Layout/overlayPaddingReset.stylex.ts

@@ -0,0 +1,73 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file overlayPaddingReset.stylex.ts
+ * @input Uses @stylexjs/stylex
+ * @output overlayPaddingReset: the container padding boundary at an overlay's root
+ * @position Layout utility, re-exported by padding.stylex.ts and Layout/index.ts.
+ *   Its own module so an overlay's eager code (useLayer) imports it without
+ *   padding.stylex.ts: a lazily loaded overlay that uses the container padding
+ *   styles there then keeps them out of the eager chunk it shares with this
+ *   module.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Padding-variable reset for overlay roots (Dialog, BottomSheet, Drawer,
+ * MobileNav, Lightbox, and every layer surface).
+ *
+ * ## Why an overlay needs this
+ *
+ * The container padding system talks to descendants through inherited custom
+ * properties: a padded container announces its padding, and children read the
+ * value either to apply it or to cancel it with a negative margin
+ * (`Section`, `Divider`, `Layout`, `Table`).
+ *
+ * Inheritance follows the DOM, but an overlay leaves its parent's visual box —
+ * a fixed/top-layer `<dialog>` is a DOM descendant of the padded page while
+ * being nowhere near it on screen. It inherits values describing padding that
+ * is not there, and its content compensates against phantom space: a `Section`
+ * inside a 640px sheet rendered 672px wide and hung off both edges.
+ *
+ * Two families leak, and they need opposite treatments:
+ *
+ * - `--container-padding-*` -> `0px`. Descendants SUBTRACT these (bleed
+ *   margins). The overlay root has no padding of its own to escape, so the
+ *   honest answer is zero. Nested containers that do set padding (a Dialog's
+ *   content wrapper) re-announce their own values below this point, so
+ *   legitimate edge-to-edge bleed inside the overlay is unaffected.
+ * - `--layout-padding-*` and `--_section-padding-propagated` -> `initial`.
+ *   Descendants ADD these, so zeroing them would strip padding rather than
+ *   restore it. `initial` makes each guaranteed-invalid, so readers fall
+ *   through their own `var(…, fallback)` chain and land on the theme default —
+ *   which is what an overlay at the top of the tree should show.
+ *
+ * `initial` is also why propagation moved off `--astryx-section-padding`: that
+ * name is public theme surface, set at the theme root, and making it invalid
+ * here would blank the theme's own section padding inside every overlay.
+ *
+ * Apply on the overlay's outermost styled element.
+ *
+ * @example
+ * ```
+ * <dialog {...stylex.props(styles.dialog, overlayPaddingReset.reset)} />
+ * ```
+ */
+export const overlayPaddingReset = stylex.create({
+  reset: {
+    // Subtracted by descendants — the overlay root has no padding to escape.
+    '--container-padding-inline-start': '0px',
+    '--container-padding-inline-end': '0px',
+    '--container-padding-block-start': '0px',
+    '--container-padding-block-end': '0px',
+    // Added by descendants — fall through to each reader's own default.
+    '--layout-padding-outer-x': 'initial',
+    '--layout-padding-outer-y': 'initial',
+    '--layout-padding-own-outer-x': 'initial',
+    '--layout-padding-own-outer-y': 'initial',
+    '--layout-padding-inner-x': 'initial',
+    '--layout-padding-inner-y': 'initial',
+    '--_section-padding-propagated': 'initial',
+  },
+});