@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/src/Layer/useTouchTrigger.ts

@@ -0,0 +1,366 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTouchTrigger.ts
+ * @input Touch trigger mode, layer open state, trigger ref, show/hide callbacks
+ * @output Exports useTouchTrigger hook, isActionTrigger, LayerTouchTrigger type
+ * @position Layer hook; shared touch behavior for useTooltip and useHoverCard
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Layer/index.ts
+ *
+ * Hover is the one trigger a touch screen cannot express. A tap synthesizes
+ * `mouseenter`, so an untreated hover layer either opens on every tap and
+ * lingers with nothing to close it, or swallows the tap the user aimed at the
+ * control underneath.
+ *
+ * What the trigger DOES decides which of those the tap deserves. A trigger
+ * that performs an action — a button, a link, a form control — keeps its tap:
+ * the layer stays shut, because the tap already has somewhere to go and a hint
+ * about a control the user just operated is noise. A trigger that performs no
+ * action — an info icon, an abbreviation, a truncated label — has nothing to
+ * lose, so the tap opens the layer and the next tap outside dismisses it. That
+ * is `auto`; `tap` and `none` state the choice outright, which is what an
+ * icon-button whose only job is to reveal the layer needs.
+ */
+
+import {useCallback, useEffect, useRef, type RefObject} from 'react';
+import {
+  getInteractionModality,
+  trackInteractionModality,
+} from '../utils/interactionModality';
+
+/**
+ * How a hover layer behaves on a touch pointer.
+ *
+ * - `auto`: tap-to-open, unless the trigger performs an action of its own
+ * - `tap`: always tap-to-open, even on a trigger that performs an action
+ * - `none`: never open on touch
+ */
+export type LayerTouchTrigger = 'auto' | 'tap' | 'none';
+
+/**
+ * Pointer types whose *press* is a tap rather than a click.
+ *
+ * A pen belongs here but not in the arrival path: in detection range it hovers
+ * — firing `pointerenter`/`pointermove` with no contact, exactly as a mouse
+ * does, on a device where `(hover: hover)` matches — and only becomes a tap
+ * once it lands. See `handlePointerEnter`.
+ */
+const TOUCH_POINTER_TYPES = new Set(['touch', 'pen']);
+
+/**
+ * ARIA roles that make an element do something when activated. An explicit
+ * role wins over the tag: `<button role="presentation">` is scenery, and a
+ * `<span role="button">` is a real control.
+ */
+const ACTION_ROLES = new Set([
+  'button',
+  'checkbox',
+  'combobox',
+  'link',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'option',
+  'radio',
+  'searchbox',
+  'slider',
+  'spinbutton',
+  'switch',
+  'tab',
+  'textbox',
+]);
+
+/**
+ * Whether activating this element does something other than reveal the layer.
+ *
+ * Deliberately narrower than "focusable": the wrapper a text-only Tooltip
+ * renders carries `tabindex=0` so keyboard users can reach the hint, and it
+ * still performs no action.
+ *
+ * True only decides that the layer stays shut — the tap itself is never
+ * swallowed. Nothing here calls `preventDefault` or `stopPropagation`, so an
+ * inert trigger that happens to carry its own `onClick` (a `<div onClick>`
+ * with no role) gets both: the layer opens and the handler runs.
+ */
+export function isActionTrigger(element: HTMLElement): boolean {
+  const role = element.getAttribute('role');
+  if (role != null && role !== '') {
+    return ACTION_ROLES.has(role);
+  }
+
+  switch (element.tagName) {
+    case 'BUTTON':
+    case 'INPUT':
+    case 'LABEL':
+    case 'SELECT':
+    case 'SUMMARY':
+    case 'TEXTAREA':
+      return true;
+    case 'A':
+    case 'AREA':
+      return element.hasAttribute('href');
+    default:
+      return isEditable(element);
+  }
+}
+
+/**
+ * Whether typing into this element edits it. Reads the attribute as well as
+ * the property: jsdom does not implement `isContentEditable`, and an editor
+ * that is an action in the browser must not be inert under test.
+ */
+function isEditable(element: HTMLElement): boolean {
+  if (element.isContentEditable === true) {
+    return true;
+  }
+  const attribute = element.getAttribute('contenteditable');
+  return attribute != null && attribute !== 'false';
+}
+
+export interface UseTouchTriggerOptions {
+  /** How the layer should behave on a touch pointer. */
+  touchTrigger: LayerTouchTrigger;
+
+  /** Whether the layer's triggers are live at all. */
+  isEnabled: boolean;
+
+  /**
+   * Whether the consumer controls visibility. A controlled layer is never
+   * toggled by a tap — its visibility is the consumer's to own.
+   */
+  isControlled: boolean;
+
+  /** Whether the layer is currently open. */
+  isOpen: boolean;
+
+  /** Element id of the layer surface, so taps inside it count as inside. */
+  layerId: string;
+
+  /** The trigger element the layer is anchored to. */
+  triggerRef: RefObject<HTMLElement | null>;
+
+  /** Open the layer immediately, with no hover delay. */
+  show: () => void;
+
+  /** Close the layer immediately. */
+  hide: () => void;
+}
+
+export interface UseTouchTriggerReturn {
+  /**
+   * Whether the pointer in play on this trigger has no hover of its own: a
+   * finger, or a pen that has landed. A hovering pen reads as false, because
+   * it hovers.
+   */
+  isTouchPointerRef: RefObject<boolean>;
+
+  /**
+   * Whether the interaction in flight is a touch one. Unlike the raw ref this
+   * goes false again as soon as the user reaches for the keyboard, so
+   * focus-driven triggers stay available after a tap.
+   */
+  isTouchInteraction: () => boolean;
+
+  /**
+   * Attach to the trigger: records pointer type ahead of synthesized hover.
+   * Arrival alone only marks a finger — a pen hovers, so it is left to the
+   * hover path until it presses.
+   */
+  handlePointerEnter: (event: PointerEvent) => void;
+
+  /**
+   * Attach to the trigger. Returns true when the press was a touch one and
+   * this hook has dealt with it, meaning the caller's own pointer-down
+   * behavior must not also run.
+   */
+  handlePointerDown: (event: PointerEvent) => boolean;
+
+  /** Forget a tap-open. Call from every other close path (Escape, controlled). */
+  clearTapOpen: () => void;
+}
+
+/**
+ * Touch behavior shared by the hover layers.
+ *
+ * @example
+ * ```
+ * const touch = useTouchTrigger({
+ *   touchTrigger,
+ *   isEnabled,
+ *   isControlled: isOpen !== undefined,
+ *   isOpen: layer.isOpen,
+ *   layerId: layer.id,
+ *   triggerRef,
+ *   show: showNow,
+ *   hide: hideNow,
+ * });
+ * ```
+ */
+export function useTouchTrigger(
+  options: UseTouchTriggerOptions,
+): UseTouchTriggerReturn {
+  const {
+    touchTrigger,
+    isEnabled,
+    isControlled,
+    isOpen,
+    layerId,
+    triggerRef,
+    show,
+    hide,
+  } = options;
+
+  const isTouchPointerRef = useRef(false);
+  // Mirrors `isOpen` for synchronous reads inside the pointer handler, which
+  // runs outside React's render and would otherwise close over a stale value.
+  const isOpenRef = useRef(isOpen);
+  isOpenRef.current = isOpen;
+
+  // Latest values for the document listener, which outlives the render that
+  // armed it.
+  const hideRef = useRef(hide);
+  hideRef.current = hide;
+  const layerIdRef = useRef(layerId);
+  layerIdRef.current = layerId;
+
+  // 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
+  // pointer-leave, and a controlled one is not ours to close.
+  const isTapOpenRef = useRef(false);
+  const outsideListenerRef = useRef<((event: PointerEvent) => void) | null>(
+    null,
+  );
+
+  useEffect(() => {
+    trackInteractionModality();
+  }, []);
+
+  const disarmOutsideDismiss = useCallback(() => {
+    isTapOpenRef.current = false;
+    const listener = outsideListenerRef.current;
+    if (listener == null) {
+      return;
+    }
+    outsideListenerRef.current = null;
+    document.removeEventListener('pointerdown', listener, true);
+  }, []);
+
+  // Capture phase, so a trigger that stops propagation cannot strand an open
+  // layer. The opening tap's own capture phase at the document has already
+  // passed by the time this runs, so the listener never sees it.
+  const armOutsideDismiss = useCallback(() => {
+    isTapOpenRef.current = true;
+    if (outsideListenerRef.current != null) {
+      return;
+    }
+
+    const handleOutsidePointerDown = (event: PointerEvent) => {
+      const target = event.target as Node | null;
+      if (target != null) {
+        // The trigger's own handler owns the toggle.
+        if (triggerRef.current?.contains(target) === true) {
+          return;
+        }
+        // Hover card content is interactive; a tap inside it is not a dismiss.
+        if (
+          document.getElementById(layerIdRef.current)?.contains(target) === true
+        ) {
+          return;
+        }
+      }
+      disarmOutsideDismiss();
+      hideRef.current();
+    };
+
+    outsideListenerRef.current = handleOutsidePointerDown;
+    document.addEventListener('pointerdown', handleOutsidePointerDown, true);
+  }, [triggerRef, disarmOutsideDismiss]);
+
+  useEffect(() => disarmOutsideDismiss, [disarmOutsideDismiss]);
+
+  const isTouchInteraction = useCallback(
+    () => isTouchPointerRef.current && getInteractionModality() === 'pointer',
+    [],
+  );
+
+  const handlePointerEnter = useCallback((event: PointerEvent) => {
+    // Only a finger is hoverless on arrival. A pen in detection range hovers
+    // like a mouse, and treating its arrival as touch would bail out of the
+    // hover path and leave a stylus user with no tooltip at all. A pen that
+    // presses is a tap, and `handlePointerDown` still reads it as one.
+    isTouchPointerRef.current = event.pointerType === 'touch';
+  }, []);
+
+  const handlePointerDown = useCallback(
+    (event: PointerEvent): boolean => {
+      const isTouch = TOUCH_POINTER_TYPES.has(event.pointerType);
+      isTouchPointerRef.current = isTouch;
+
+      if (!isTouch || isControlled) {
+        return false;
+      }
+
+      const trigger = triggerRef.current;
+      const mode =
+        touchTrigger === 'auto'
+          ? trigger != null && isActionTrigger(trigger)
+            ? 'none'
+            : 'tap'
+          : touchTrigger;
+
+      if (mode === 'none' || !isEnabled) {
+        // A layer left open by an earlier tap must not survive the next one.
+        disarmOutsideDismiss();
+        hide();
+        return true;
+      }
+
+      // A lazily mounted layer reports `isOpen` a tick after `show()`, so the
+      // tap's own bookkeeping is what makes the second tap a close.
+      if (isOpenRef.current || isTapOpenRef.current) {
+        disarmOutsideDismiss();
+        hide();
+        return true;
+      }
+
+      armOutsideDismiss();
+      show();
+      return true;
+    },
+    [
+      touchTrigger,
+      isEnabled,
+      isControlled,
+      triggerRef,
+      show,
+      hide,
+      armOutsideDismiss,
+      disarmOutsideDismiss,
+    ],
+  );
+
+  // A layer closed by any other path (Escape, a consumer, the browser) leaves
+  // no tap-open to dismiss. Only a true open→closed transition counts: a
+  // lazily mounted layer still reports `false` for a tick after the tap asked
+  // it to open, and reading that as a close would disarm the dismissal the
+  // tap-open just armed.
+  const wasOpenRef = useRef(isOpen);
+  useEffect(() => {
+    if (wasOpenRef.current && !isOpen) {
+      disarmOutsideDismiss();
+    }
+    wasOpenRef.current = isOpen;
+  }, [isOpen, disarmOutsideDismiss]);
+
+  return {
+    isTouchPointerRef,
+    isTouchInteraction,
+    handlePointerEnter,
+    handlePointerDown,
+    clearTapOpen: disarmOutsideDismiss,
+  };
+}

package/src/Layout/Layout.doc.mjs

@@ -93,6 +93,24 @@ export const docs = {
       description: 'Height behavior: fill the container or grow with content.',
       default: "'fill'",
     },
+    {
+      name: 'contentWidth',
+      type: 'number | string',
+      description:
+        'Maximum width of the content within each slot (header, content, footer, panels), centered when narrower than the available space. Dividers stay full-bleed. Numbers are pixels, strings are used as-is (e.g. `60ch`). Common page widths: 640 for forms, settings, and text-focused pages; 960 for content pages and wider layouts.',
+    },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        "Padding at the layout's outer edges using the spacing scale.",
+    },
+    {
+      name: 'defaultHasDividers',
+      type: 'boolean',
+      description:
+        "Default divider visibility for LayoutHeader and LayoutFooter children. Headers and footers that don't pass `hasDivider` use this value; when unset, nested layouts inherit from their parent context.",
+    },
   ],
   components: [
     {name: 'LayoutHeader'},

package/src/Layout/container.stylex.ts

@@ -28,8 +28,10 @@
  * }
  * ```
  *
- * Internal variables (`--layout-padding-inner-x`, `--container-padding-*`)
- * are implementation details and must not be referenced by themes.
+ * Internal variables (`--layout-padding-inner-x`, `--container-padding-*`,
+ * `--_section-padding-propagated`) are implementation details and must not be
+ * referenced by themes. They also do not cross an overlay boundary — see
+ * `overlayPaddingReset` in padding.stylex.ts.
  *
  * SYNC: When modified, update /packages/core/src/Layout/Layout.doc.mjs
  */
@@ -105,7 +107,13 @@ const cardBlockEnd = `var(--astryx-card-padding-block-end, ${cardShorthand})`;
 // Section padding chains: --astryx-* then the next specificity level, terminating
 // at --spacing-4. Built as chained const strings (no function calls) so StyleX
 // can statically analyze them; see naming.ts for the prefix policy.
-const sectionShorthand = `var(--astryx-section-padding, ${SP4})`;
+// `--_section-padding-propagated` (set by an ancestor Section with explicit
+// padding) is read AHEAD of the public theme token, so a propagated value
+// still wins over the theme for nested sections. Splitting the two names is
+// what lets an overlay drop the inherited value at its boundary while keeping
+// the theme's — see `overlayPaddingReset` in padding.stylex.ts.
+const sectionThemeShorthand = `var(--astryx-section-padding, ${SP4})`;
+const sectionShorthand = `var(--_section-padding-propagated, ${sectionThemeShorthand})`;
 const sectionInline = `var(--astryx-section-padding-inline, ${sectionShorthand})`;
 const sectionInlineStart = `var(--astryx-section-padding-inline-start, ${sectionInline})`;
 const sectionInlineEnd = `var(--astryx-section-padding-inline-end, ${sectionInline})`;

package/src/Layout/index.ts

@@ -19,6 +19,10 @@ export type {
   SpacingToken,
 } from './container.stylex';
 
+// 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';
+
 // Edge compensation utility
 export {edgeCompSlot, EDGE_COMP_ATTR} from './edgeCompensation.stylex';
 

package/src/Layout/overlayPaddingReset.test.tsx

@@ -0,0 +1,222 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file overlayPaddingReset.test.tsx
+ * @input Uses vitest, @testing-library/react, overlay components from core
+ * @output Tests that overlay roots stop the container padding system at their
+ *   boundary, and that the public theme token still crosses it
+ * @position Layout tests; validates overlayPaddingReset in padding.stylex.ts
+ *
+ * The container padding system talks to descendants through INHERITED custom
+ * properties, but an overlay leaves its parent's visual box while staying a DOM
+ * descendant of it. Every overlay root therefore has to stop those values (see
+ * #5208: a Section in a 640px sheet rendered 672px wide).
+ *
+ * jsdom does no layout, so these assert on the custom properties themselves —
+ * the definitions the layout is computed from. The widths they stand in for are
+ * verified in a browser; see the PR description.
+ *
+ * SYNC: When an overlay is added, add it to OVERLAYS below.
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {render, screen} from '@testing-library/react';
+import type {ReactNode} from 'react';
+import {Dialog} from '../Dialog';
+import {BottomSheet} from '../BottomSheet';
+import {MobileNav} from '../MobileNav';
+import {Lightbox} from '../Lightbox';
+import {Popover} from '../Popover';
+import {Section} from '../Section';
+
+// jsdom implements neither the <dialog> methods nor matchMedia.
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockReturnValue({
+      matches: false,
+      media: '',
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }),
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+/**
+ * Values descendants SUBTRACT (bleed margins). The overlay root has no padding
+ * of its own to escape, so these must read a literal zero.
+ */
+const SUBTRACTED = [
+  '--container-padding-inline-start',
+  '--container-padding-inline-end',
+  '--container-padding-block-start',
+  '--container-padding-block-end',
+];
+
+/**
+ * Values descendants ADD. These must be guaranteed-invalid (`initial`) rather
+ * than zero, so readers fall through to their own default instead of losing
+ * their padding — a computed empty string is what `initial` looks like here.
+ */
+const CLEARED = [
+  '--layout-padding-outer-x',
+  '--layout-padding-outer-y',
+  '--layout-padding-inner-x',
+  '--layout-padding-inner-y',
+  '--_section-padding-propagated',
+];
+
+/** What a cleared custom property reads back as. See the assertion below. */
+const CLEARED_READBACK = ['', 'initial'];
+
+/** Each overlay, rendered open inside a page Section that leaks 40px. */
+const OVERLAYS: {
+  name: string;
+  render: (child: ReactNode) => ReactNode;
+  root: () => HTMLElement;
+}[] = [
+  {
+    name: 'Dialog',
+    render: child => (
+      <Dialog isOpen onOpenChange={() => {}}>
+        {child}
+      </Dialog>
+    ),
+    root: () => screen.getByRole('dialog'),
+  },
+  {
+    name: 'BottomSheet',
+    render: child => (
+      <BottomSheet isOpen onOpenChange={() => {}} label="S">
+        {child}
+      </BottomSheet>
+    ),
+    root: () =>
+      document.querySelector<HTMLElement>(
+        '.astryx-bottom-sheet',
+      ) as HTMLElement,
+  },
+  {
+    name: 'MobileNav',
+    render: child => (
+      <MobileNav isOpen onOpenChange={() => {}} label="N">
+        {child}
+      </MobileNav>
+    ),
+    root: () => screen.getByRole('dialog'),
+  },
+  {
+    name: 'Lightbox',
+    render: () => (
+      <Lightbox
+        isOpen
+        onOpenChange={() => {}}
+        media={{src: 'a.png', alt: 'a'}}
+      />
+    ),
+    root: () => screen.getByRole('dialog'),
+  },
+  {
+    name: 'Popover (useLayer surface)',
+    render: child => (
+      <Popover isOpen onOpenChange={() => {}} label="P" content={child}>
+        <button type="button">t</button>
+      </Popover>
+    ),
+    root: () => document.querySelector<HTMLElement>('[popover]') as HTMLElement,
+  },
+];
+
+describe('overlayPaddingReset', () => {
+  describe.each(OVERLAYS)('$name', ({render: renderOverlay, root}) => {
+    it('zeroes the values descendants subtract', () => {
+      render(<Section padding={10}>{renderOverlay(<div>c</div>)}</Section>);
+      const computed = getComputedStyle(root());
+      for (const name of SUBTRACTED) {
+        expect(computed.getPropertyValue(name), name).toBe('0px');
+      }
+    });
+
+    it('clears the values descendants add, so they fall to their default', () => {
+      render(<Section padding={10}>{renderOverlay(<div>c</div>)}</Section>);
+      const computed = getComputedStyle(root());
+      for (const name of CLEARED) {
+        // A browser resolves `initial` on a custom property to the
+        // guaranteed-invalid value and reports '' here; jsdom does not
+        // implement that and echoes the keyword. Either proves the
+        // declaration landed — and neither is the leaked '40px'.
+        expect(CLEARED_READBACK, name).toContain(
+          computed.getPropertyValue(name),
+        );
+      }
+    });
+  });
+
+  it('does not clear the public theme token', () => {
+    // The reset clears the PRIVATE propagation var only. The public
+    // `--astryx-section-padding` is theme surface, set once at the theme root,
+    // so it has to keep reaching inside every overlay — clearing it would
+    // blank a theme's section padding in every dialog. That is the whole
+    // reason the two names were split, and it is the mistake a later
+    // "simplification" would most plausibly make.
+    //
+    // jsdom does not inherit custom properties, so the cascade cannot show
+    // this; assert it where it is decided instead. (Verified in a browser: a
+    // theme's 20px still reaches a Section inside a Dialog nested under a
+    // 40px page Section.)
+    const source = readFileSync(join(__dirname, 'padding.stylex.ts'), 'utf8');
+    const reset = source.slice(
+      source.indexOf('export const overlayPaddingReset'),
+    );
+    expect(reset).toContain("'--_section-padding-propagated': 'initial'");
+    expect(reset).not.toContain('--astryx-section-padding');
+  });
+
+  it("stops an ancestor Section's propagated padding at the boundary", () => {
+    // The page Section propagates 40px. Without the reset it would reach the
+    // Section inside the overlay, which would pad itself 40px instead of the
+    // theme default — the second half of #5208.
+    render(
+      <Section padding={10}>
+        <Dialog isOpen onOpenChange={() => {}}>
+          <div data-testid="content">c</div>
+        </Dialog>
+      </Section>,
+    );
+    const dialog = screen.getByRole('dialog');
+    expect(CLEARED_READBACK).toContain(
+      getComputedStyle(dialog).getPropertyValue(
+        '--_section-padding-propagated',
+      ),
+    );
+    // ...while the page Section outside the overlay still propagates it.
+    // (jsdom does not resolve the token reference to its 40px value.)
+    const pageSection = document.querySelector<HTMLElement>('.astryx-section');
+    expect(
+      getComputedStyle(pageSection as HTMLElement).getPropertyValue(
+        '--_section-padding-propagated',
+      ),
+    ).toBe('var(--spacing-10)');
+  });
+});