@astryxdesign/core 0.7.7-canary.550ff21 → 0.7.7-canary.58c5b8a

package/src/Outline/useScrollSpy.ts

@@ -410,9 +410,9 @@ export function useScrollSpy({
     const onSettle = () => finish(true);
     const onManual = () => finish(false);
     const onKeyDown = (event: KeyboardEvent) => {
-      // A key the outline itself consumed (arrow roving focus, Space
-      // activation) is prevented, so the browser will not scroll — it is not a
-      // manual scroll intent and must not cancel the navigation it just began.
+      // The outline prevents the Space key that activates a link. The
+      // browser then does not scroll. So this key is not a manual scroll, and
+      // it does not end the navigation.
       if (!event.defaultPrevented && SCROLL_KEYS.has(event.key)) {
         finish(false);
       }

package/src/Popover/usePopover.tsx

@@ -19,7 +19,7 @@
 import React, {useCallback, useEffect, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {useLayer, type ContextRenderProps} from '../Layer/useLayer';
-import {useFocusTrap} from '../hooks/useFocusTrap';
+import {useFocusTrapInternal} from '../hooks/useFocusTrap';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {
@@ -34,6 +34,7 @@ import {rtlStyles} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {mergeProps} from '../utils/mergeProps';
+import {isFocusDetached} from '../utils/focusReturn';
 import {themeProps} from '../utils/themeProps';
 import {paddingStyles} from '../Layout/padding.stylex';
 import type {SpacingStep} from '../utils/types';
@@ -422,28 +423,51 @@ function usePopoverImplementation(
 
   // Track whether to skip auto-focus for the current open event
   const skipAutoFocusRef = useRef(false);
+  // Whether `show` focused a content control within the opening event.
+  const hasFocusedInGestureRef = useRef(false);
+
+  // Set when the layer reports it has shown, so `show` can tell a popover
+  // that opened within the call from one whose content mounts later.
+  const hasShownRef = useRef(false);
+  const handleLayerShow = useCallback(() => {
+    hasShownRef.current = true;
+    onShow?.();
+  }, [onShow]);
 
   // Core layer for popover positioning
   const layer = useLayer({
     mode: 'context',
     lightDismiss: hasLightDismiss,
-    onShow,
+    onShow: handleLayerShow,
     onHide,
   });
 
   // Focus trap for the popover content. Escape stays registered while light
   // dismiss is on (native popover="auto" closes on Escape regardless), so a
   // host Dialog keeps deferring to this trap instead of double-dismissing.
-  const {containerRef: contentRef, focusFirst} = useFocusTrap<HTMLDivElement>({
-    isActive: layer.isOpen,
-    onEscape: hasEscapeDismiss || hasLightDismiss ? layer.hide : undefined,
-  });
+  // The element focused when `show` ran: initial focus may move inside before
+  // the trap activates, so the trap restores focus here instead.
+  const openerRef = useRef<HTMLElement | null>(null);
+  const getRestoreTarget = useCallback(() => openerRef.current, []);
+  const {containerRef: contentRef, focusFirst} =
+    useFocusTrapInternal<HTMLDivElement>({
+      isActive: layer.isOpen,
+      onEscape: hasEscapeDismiss || hasLightDismiss ? layer.hide : undefined,
+      getRestoreTarget,
+    });
 
   const focusInitialTarget = useCallback(() => {
     const container = contentRef.current;
     if (!container) {
       return;
     }
+    // Focus already on a control inside (set in `onShow`, or a press in the
+    // content) is where the user or the caller wants it; moving it would
+    // undo that.
+    const active = container.ownerDocument.activeElement;
+    if (active != null && active !== container && container.contains(active)) {
+      return;
+    }
     if (focusFirstContentControl(container)) {
       return;
     }
@@ -459,16 +483,23 @@ function usePopoverImplementation(
     // Reset the per-open focus preference after the popover closes.
     if (!layer.isOpen) {
       skipAutoFocusRef.current = false;
+      hasFocusedInGestureRef.current = false;
       return;
     }
     if (hasAutoFocus && !skipAutoFocusRef.current) {
       // Wait a frame so the content is mounted. A popover that closes or
       // unmounts first cancels it: the frame would otherwise move focus into
       // content that is no longer shown, after the close had left it alone.
-      const frame = requestAnimationFrame(focusInitialTarget);
+      const frame = requestAnimationFrame(() => {
+        const doc = contentRef.current?.ownerDocument ?? document;
+        if (hasFocusedInGestureRef.current && !isFocusDetached(doc)) {
+          return;
+        }
+        focusInitialTarget();
+      });
       return () => cancelAnimationFrame(frame);
     }
-  }, [layer.isOpen, hasAutoFocus, focusInitialTarget]);
+  }, [layer.isOpen, hasAutoFocus, focusInitialTarget, contentRef]);
 
   // Combined ref for trigger element (layer anchor + our ref). It is keyed on
   // the layer's own ref, not the whole layer: the layer object changes with
@@ -490,9 +521,40 @@ function usePopoverImplementation(
   const show = useCallback(
     (showOptions?: {skipAutoFocus?: boolean}) => {
       skipAutoFocusRef.current = showOptions?.skipAutoFocus ?? false;
+      hasShownRef.current = false;
+      const activeElement = (
+        triggerElementRef.current?.ownerDocument ?? document
+      ).activeElement as HTMLElement | null;
+      openerRef.current =
+        activeElement != null && !contentRef.current?.contains(activeElement)
+          ? activeElement
+          : null;
       layer.show();
+      // When the content is already mounted, the layer shows it within this
+      // call, so initial focus lands within the event that opened it: iOS
+      // raises its keyboard only for a focus made while the tap is still
+      // being handled. The frame in the effect above stays for content that
+      // mounts later.
+      // Only a content control already rendered takes focus here; content
+      // that renders on open (and the dialog-surface fallback) waits for the
+      // effect's frame.
+      const container = contentRef.current;
+      if (
+        hasShownRef.current &&
+        hasAutoFocus &&
+        !skipAutoFocusRef.current &&
+        container != null &&
+        !container.contains(container.ownerDocument.activeElement) &&
+        focusFirstContentControl(container)
+      ) {
+        // Initial focus is done. The effect's frame stays only as a fallback
+        // for focus lost to the page (content swapped in the same handler
+        // unmounts the control just focused); it must not move focus the user
+        // has since moved elsewhere.
+        hasFocusedInGestureRef.current = true;
+      }
     },
-    [layer],
+    [layer, hasAutoFocus, contentRef],
   );
 
   // Toggle function. Opening delegates to show so every route inherits the

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -65,7 +65,8 @@ export const docs = {
     {
       name: 'hasClear',
       type: 'boolean',
-      description: 'Show a clear-all button for removing all filters.',
+      description:
+        'Show a clear-all button that removes every editable filter. Read-only filters stay.',
       default: 'true',
     },
     {
@@ -173,17 +174,20 @@ export const docs = {
     {
       name: 'menuWidth',
       type: 'number',
-      description: 'Maximum width for the operator/value dropdown menu in pixels.',
+      description:
+        'Maximum width for the operator/value dropdown menu in pixels.',
     },
     {
       name: 'maxOperatorMenuItems',
       type: 'number',
-      description: 'Maximum number of items displayed in the operator dropdown.',
+      description:
+        'Maximum number of items displayed in the operator dropdown.',
     },
     {
       name: 'tokenOverflowBehavior',
       type: "'none' | 'unfocusedInline' | 'unfocusedLayer'",
-      description: 'Controls how tokens overflow when the container is too narrow. Forwarded to Tokenizer.',
+      description:
+        'Controls how tokens overflow when the container is too narrow. Forwarded to Tokenizer.',
       default: "'none'",
     },
     {
@@ -202,6 +206,25 @@ export const docs = {
       description:
         'StyleX styles for layout customization. Must be a stylex.create() value.',
     },
+    {
+      name: 'experimental',
+      type: "{presentation?: 'popover' | 'bottom-sheet' | 'adaptive'}",
+      stability: 'experimental',
+      description:
+        "Experimental options: anything in this object may change or be removed in a patch release, and omitting it keeps the stable behavior. presentation (default 'popover') chooses how the field presents filter editing. popover is the tokenizer field with its typeahead and the editor popover. bottom-sheet makes the whole field one trigger showing display-only filter tokens: it opens a Filters sheet listing the filters as rows that edit or remove a filter, with Add filter, Done, and Clear all (which asks first and keeps read-only filters); an Add filter sheet with the fields (or the content search with inline suggestions) opens above it, and a value step that stages operator → value and confirms from its footer opens above that. Dismissing a step reveals the one beneath. List values edit through the Tokenizer's own sheet. adaptive uses the bottom sheet on compact touch screens and the popover otherwise, resolved the same way Selector resolves it. In the sheet presentation menuWidth and tokenOverflowBehavior have no surface to act on and warn in development.",
+    },
+  ],
+  examples: [
+    {
+      label: 'Touch sheet on compact screens (experimental)',
+      code: `const [filters, setFilters] = useState([]);
+<PowerSearch
+  config={config}
+  filters={filters}
+  onChange={next => setFilters(next)}
+  experimental={{presentation: 'adaptive'}}
+/>`,
+    },
   ],
   // `config` and `filters` are custom values the docsite preview cannot
   // generate automatically. Keep this small, but include an initial token so
@@ -276,6 +299,22 @@ export const docs = {
   },
   theming: {
     targets: [{className: 'astryx-power-search'}],
+    vars: [
+      {
+        name: '--_power-search-sheet-hit-inset',
+        description:
+          "Outset of the invisible hit area of the touch sheet's icon-sized actions (the Filters header's Add filter and each row's remove button), applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the action to a 44px touch target without changing what is drawn.",
+        default: '0px',
+        private: true,
+      },
+      {
+        name: '--_power-search-sheet-hit-content',
+        description:
+          'Whether the touch sheet\'s invisible hit overlay exists. `none` on a fine pointer, so no ::after is generated and hover still reaches the action; `""` on a coarse one, where the overlay provides the 44px touch target.',
+        default: 'none',
+        private: true,
+      },
+    ],
   },
 };
 
@@ -336,7 +375,7 @@ export const docsZh = {
     {
       name: 'hasClear',
       type: 'boolean',
-      description: '显示清除全部按钮以移除所有过滤器。',
+      description: '显示清除全部按钮，移除可编辑的过滤器，保留只读过滤器。',
       default: 'true',
     },
     {
@@ -439,6 +478,13 @@ export const docsZh = {
       type: 'StyleXStyles',
       description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 值。',
     },
+    {
+      name: 'experimental',
+      type: "{presentation?: 'popover' | 'bottom-sheet' | 'adaptive'}",
+      stability: 'experimental',
+      description:
+        "实验性选项：此对象中的任何内容都可能在补丁版本中更改或移除；省略它即保持稳定行为。presentation（默认 'popover'）决定字段如何呈现筛选编辑：popover 为带有预输入和编辑弹出层的标记字段；bottom-sheet 将整个字段变为一个显示只读筛选标记的触发按钮——点按后打开列出筛选项的「筛选」面板，每行可编辑或移除筛选（含添加筛选、完成、全部清除；全部清除会先确认，并保留只读筛选）；列出字段（或带内联建议的内容搜索）的「添加筛选」面板在其上方打开，按运算符 → 值暂存并在底部确认的取值步骤再在其上方打开。关闭某一步会露出下方的那一步。列表值通过 Tokenizer 自身的面板编辑。adaptive 在紧凑触摸屏上使用底部面板，其他情况使用 popover，解析方式与 Selector 相同。在底部面板呈现中，menuWidth 和 tokenOverflowBehavior 没有作用对象，并会在开发环境中发出警告。",
+    },
   ],
   usage: {
     description:
@@ -507,7 +553,8 @@ export const docsDense = {
     isLabelHidden: 'Visually hides label while keeping accessible.',
     placeholder: 'Text shown when no filters selected.',
     hasAutoFocus: 'Auto-focus input on mount.',
-    hasClear: 'Show clear-all button for removing all filters.',
+    hasClear:
+      'Show clear-all button; removes editable filters, keeps read-only ones.',
     isReadOnly: 'Prevent adding, editing, or removing filters.',
     isDisabled: 'Disables entire component.',
     status: 'Validation status object w/ type + optional message.',
@@ -532,5 +579,7 @@ export const docsDense = {
     size: 'Search input+token size.',
     xstyle:
       'StyleX styles for layout customization. Must be stylex.create() value.',
+    experimental:
+      "Experimental; may change in a patch. presentation: 'popover' (default, tokenizer field + editor popover) | 'bottom-sheet' (one trigger with display-only tokens + stacked Filters / Add filter / value sheets; rows remove inline; Clear all confirms, keeps read-only; list values via Tokenizer's sheet) | 'adaptive' (sheet on compact touch, else popover).",
   },
 };