@astryxdesign/core 0.7.7-canary.f9ac85f → 0.7.7

package/src/Resizable/resizeGesture.ts

@@ -0,0 +1,368 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file resizeGesture.ts
+ * @input A handle element, a resize model (its state, and a gesture's start,
+ *   move, end and cancel), and the handle's axis, reversal and disabled state
+ * @output createResizeGesture: the window splitter's input in one place: a
+ *   pointer drag that holds its pointer, the arrow keys, Home, End and Enter,
+ *   and a double-click collapse; and the body's drag cursor
+ * @position Internal to the Resizable family. ResizeHandle forwards its React
+ *   events to it. No React, and no DOM work on import
+ */
+
+import type {ResizableDirection} from './resizableModel';
+
+/** Pixels an arrow key moves the separator; Shift moves it further. */
+export const KEYBOARD_STEP = 10;
+export const KEYBOARD_LARGE_STEP = 50;
+
+/** What a gesture reads from its region when an input arrives. */
+export interface ResizeGestureState {
+  /** The region's size in px, 0 while collapsed. */
+  readonly size: number;
+  readonly isCollapsed: boolean;
+  readonly minPx: number;
+  /** The configured maximum, Infinity when the region has none. */
+  readonly maxPx: number;
+  readonly snaps: ReadonlyArray<number>;
+  readonly collapsedSize: number;
+  readonly collapsible: boolean;
+}
+
+/** The region a gesture resizes. */
+export interface ResizeGestureModel {
+  state(): ResizeGestureState;
+  /** A gesture begins: the region holds its basis until it ends. */
+  start(): void;
+  /** The gesture has moved `delta` px from where it began. */
+  move(delta: number): void;
+  /** The gesture ends as completed. */
+  end(): void;
+  /** The gesture ends without completing. */
+  cancel(): void;
+  /**
+   * The region's own collapse and expand. They restore the size it had before
+   * it collapsed, as the APG window splitter's Enter does. Without them a
+   * toggle is a resize gesture to the minimum.
+   */
+  collapse?: () => void;
+  expand?: () => void;
+}
+
+/** The handle's configuration, read at each input. */
+export interface ResizeGestureConfig {
+  readonly direction: ResizableDirection;
+  readonly isReversed: boolean;
+  readonly isDisabled: boolean;
+}
+
+/** The fields of a pointer event the gesture reads (native or React). */
+export interface ResizeGesturePointerEvent {
+  readonly pointerId: number;
+  readonly clientX: number;
+  readonly clientY: number;
+  readonly currentTarget: EventTarget | null;
+  preventDefault(): void;
+  stopPropagation(): void;
+}
+
+/** The fields of a key event the gesture reads (native or React). */
+export interface ResizeGestureKeyEvent {
+  readonly key: string;
+  readonly shiftKey: boolean;
+  preventDefault(): void;
+}
+
+export interface ResizeGesture {
+  pointerDown(event: ResizeGesturePointerEvent): void;
+  pointerMove(event: ResizeGesturePointerEvent): void;
+  pointerUp(event: ResizeGesturePointerEvent): void;
+  /** A `pointercancel` or a `lostpointercapture`. */
+  pointerCancel(event: ResizeGesturePointerEvent): void;
+  keyDown(event: ResizeGestureKeyEvent): void;
+  doubleClick(): void;
+  /** Whether a pointer drag is in flight. */
+  readonly isDragging: boolean;
+  /**
+   * Ends a drag in flight as cancelled, for a handle that goes away mid-drag.
+   * It releases the pointer and the body's drag cursor, and tells the region
+   * that the gesture is over.
+   */
+  interrupt(): void;
+}
+
+/**
+ * Drag feedback lives on the page's `<body>`, not on the handle. During a
+ * drag the pointer moves over whatever the panels contain, and the resize
+ * cursor must hold there.
+ */
+function applyBodyDragStyles(isHorizontal: boolean): void {
+  document.body.style.cursor = isHorizontal ? 'col-resize' : 'row-resize';
+  document.body.style.userSelect = 'none';
+}
+
+function clearBodyDragStyles(): void {
+  document.body.style.cursor = '';
+  document.body.style.userSelect = '';
+}
+
+/**
+ * The snap point `count` points away from the region's current size in
+ * `direction` (+1 grows, -1 shrinks). A point beyond the minimum or the
+ * maximum counts as that bound. When fewer points remain, the nearest end
+ * point serves, or the current size when the region is already there.
+ */
+function adjacentSnapPoint(
+  state: ResizeGestureState,
+  direction: 1 | -1,
+  count: number,
+): number {
+  const points = [
+    ...new Set(
+      state.snaps.map(p => Math.min(state.maxPx, Math.max(state.minPx, p))),
+    ),
+  ].sort((a, b) => a - b);
+  const {size} = state;
+  const ahead =
+    direction > 0
+      ? points.filter(p => p > size)
+      : points.filter(p => p < size).reverse();
+  if (ahead.length === 0) {
+    return size;
+  }
+  return ahead[Math.min(count, ahead.length) - 1];
+}
+
+function step(model: ResizeGestureModel, delta: number): void {
+  model.start();
+  model.move(delta);
+  model.end();
+}
+
+/**
+ * Collapse an open pane, or restore a collapsed one to the size it had before
+ * it collapsed, with the region's own collapse and expand. A region without
+ * them falls back to a resize gesture to the minimum. That gesture cannot
+ * reopen a pane whose minimum sits below its collapse threshold.
+ */
+function toggleCollapse(model: ResizeGestureModel): void {
+  const state = model.state();
+  if (model.collapse != null && model.expand != null) {
+    if (state.isCollapsed) {
+      model.expand();
+    } else {
+      model.collapse();
+    }
+    return;
+  }
+  step(model, state.isCollapsed ? state.minPx : -state.size);
+}
+
+/**
+ * The window splitter's input for one handle. A drag takes pointer capture
+ * on the element the press landed on. The rest of the gesture then goes to
+ * that element. Without capture, the browser hit-tests each move, and an
+ * embedded frame under the pointer takes the drag.
+ */
+export function createResizeGesture(
+  getHandle: () => Element | null,
+  model: ResizeGestureModel,
+  getConfig: () => ResizeGestureConfig,
+  onDraggingChange?: (isDragging: boolean) => void,
+): ResizeGesture {
+  let drag: {
+    pointerId: number;
+    startPos: number;
+    rtl: number;
+    target: Element | null;
+  } | null = null;
+
+  const rtlMultiplier = (): number => {
+    const handle = getHandle();
+    if (handle == null) {
+      return 1;
+    }
+    const view = handle.ownerDocument.defaultView;
+    return view?.getComputedStyle(handle).direction === 'rtl' ? -1 : 1;
+  };
+
+  const clearDrag = () => {
+    const ending = drag;
+    drag = null;
+    const target = ending?.target;
+    if (
+      ending != null &&
+      target != null &&
+      target.hasPointerCapture?.(ending.pointerId) === true
+    ) {
+      target.releasePointerCapture(ending.pointerId);
+    }
+    if (ending != null) {
+      clearBodyDragStyles();
+    }
+    onDraggingChange?.(false);
+  };
+
+  return {
+    get isDragging() {
+      return drag != null;
+    },
+
+    pointerDown(event) {
+      const config = getConfig();
+      if (config.isDisabled || drag != null) {
+        return;
+      }
+      event.preventDefault();
+      event.stopPropagation();
+      // An element from another document (an iframe, a popup) is not an
+      // instance of this page's Element, so test for the capture API itself.
+      const current = event.currentTarget as Element | null;
+      const target =
+        typeof current?.setPointerCapture === 'function' ? current : null;
+      target?.setPointerCapture?.(event.pointerId);
+      const isHorizontal = config.direction === 'horizontal';
+      drag = {
+        pointerId: event.pointerId,
+        startPos: isHorizontal ? event.clientX : event.clientY,
+        rtl: isHorizontal ? rtlMultiplier() : 1,
+        target,
+      };
+      onDraggingChange?.(true);
+      model.start();
+      applyBodyDragStyles(isHorizontal);
+    },
+
+    pointerMove(event) {
+      if (drag == null || drag.pointerId !== event.pointerId) {
+        return;
+      }
+      const config = getConfig();
+      const position =
+        config.direction === 'horizontal' ? event.clientX : event.clientY;
+      const sign = config.isReversed ? -1 : 1;
+      model.move((position - drag.startPos) * drag.rtl * sign);
+    },
+
+    pointerUp(event) {
+      if (drag?.pointerId !== event.pointerId) {
+        return;
+      }
+      clearDrag();
+      model.end();
+    },
+
+    // Serves pointercancel and lostpointercapture alike: an interrupted drag
+    // ends without a resize end. The implicit release after every pointerup
+    // or pointercancel also fires lostpointercapture. By then the drag is
+    // already cleared, and this is a no-op.
+    pointerCancel(event) {
+      if (drag?.pointerId !== event.pointerId) {
+        return;
+      }
+      clearDrag();
+      model.cancel();
+    },
+
+    interrupt() {
+      if (drag == null) {
+        return;
+      }
+      clearDrag();
+      model.cancel();
+    },
+
+    keyDown(event) {
+      const config = getConfig();
+      if (config.isDisabled) {
+        return;
+      }
+      const state = model.state();
+      const isHorizontal = config.direction === 'horizontal';
+      const sign = config.isReversed ? -1 : 1;
+      const keyStep = event.shiftKey ? KEYBOARD_LARGE_STEP : KEYBOARD_STEP;
+      const rtl = isHorizontal ? rtlMultiplier() : 1;
+
+      // The pane's grow direction on this key: ArrowRight/Down grow unless the
+      // layout is reversed or, on the inline axis, right-to-left.
+      const grows = (key: string) =>
+        (key === 'ArrowRight' || key === 'ArrowDown'
+          ? 1
+          : key === 'ArrowLeft' || key === 'ArrowUp'
+            ? -1
+            : 0) *
+          (isHorizontal ? rtl : 1) *
+          sign >
+        0;
+
+      switch (event.key) {
+        case 'ArrowRight':
+        case 'ArrowDown':
+        case 'ArrowLeft':
+        case 'ArrowUp': {
+          event.preventDefault();
+          if (state.isCollapsed) {
+            // A collapsed pane answers only the grow arrow. It opens one step
+            // above its minimum, the value the separator announces while
+            // collapsed. If the collapse threshold is larger, it opens there.
+            // A bare step would stay below the threshold and leave the pane
+            // closed. The shrink arrow is a no-op.
+            if (grows(event.key)) {
+              step(model, Math.max(state.minPx + keyStep, state.collapsedSize));
+            }
+            break;
+          }
+          if (state.snaps.length > 0) {
+            // With snap points the region rests only on a point, so a pixel
+            // step would snap straight back. The arrow moves to the adjacent
+            // point in its direction instead, two points with Shift, within
+            // the bounds.
+            step(
+              model,
+              adjacentSnapPoint(
+                state,
+                grows(event.key) ? 1 : -1,
+                event.shiftKey ? 2 : 1,
+              ) - state.size,
+            );
+            break;
+          }
+          const direction =
+            event.key === 'ArrowRight' || event.key === 'ArrowDown' ? 1 : -1;
+          step(model, direction * keyStep * (isHorizontal ? rtl : 1) * sign);
+          break;
+        }
+        case 'Home': {
+          event.preventDefault();
+          step(model, state.minPx - state.size);
+          break;
+        }
+        case 'End': {
+          event.preventDefault();
+          // Only a configured maximum is the region's own limit. The reported
+          // stand-in for an unbounded region is where the pane could reach,
+          // not where End may move it.
+          if (state.maxPx !== Infinity) {
+            step(model, state.maxPx - state.size);
+          }
+          break;
+        }
+        case 'Enter': {
+          event.preventDefault();
+          if (state.collapsible) {
+            toggleCollapse(model);
+          }
+          break;
+        }
+      }
+    },
+
+    doubleClick() {
+      if (getConfig().isDisabled || !model.state().collapsible) {
+        return;
+      }
+      toggleCollapse(model);
+    },
+  };
+}

package/src/SideNav/SideNavItem.tsx

@@ -72,7 +72,7 @@ import {
   SideNavCollapseContext,
 } from './SideNavCollapseContext';
 import {useSideNavRenderMode} from './SideNavRenderContext';
-import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
+import {useCloseMobileDrawerOnActivate} from '../AppShell/useCloseMobileDrawerOnActivate';
 import {themeProps} from '../utils/themeProps';
 import {disabledInteractionProps} from '../utils/disabledInteraction';
 
@@ -535,8 +535,8 @@ export function SideNavItem({
   const t = useComponentTranslator();
   const {isCollapsed} = useSideNavCollapse();
   const renderMode = useSideNavRenderMode();
-  const {closeMobileNav} = useAppShellMobile();
   const isInDrawer = renderMode === 'drawer' || renderMode === 'drawer-content';
+  const closeDrawerAfter = useCloseMobileDrawerOnActivate(isInDrawer);
   const id = useId();
   const hasChildren = !!children;
   const depth = use(SideNavItemDepthContext);
@@ -625,11 +625,7 @@ export function SideNavItem({
       toggleItemCollapse();
       return;
     }
-    onClick?.(e);
-    // Close the mobile nav when a nav item is activated inside the drawer
-    if (isInDrawer) {
-      closeMobileNav();
-    }
+    closeDrawerAfter(onClick)?.(e);
   };
 
   const handleToggleClick = (e: React.MouseEvent) => {

package/src/Token/Token.tsx

@@ -17,7 +17,7 @@
  * - /packages/cli/assets/templates/blocks/components/Token/ (showcase blocks)
  */
 
-import type {ReactNode} from 'react';
+import {use, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -41,6 +41,7 @@ import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import type {TokenColorMap} from './index';
 import {disabledInteractionProps} from '../utils/disabledInteraction';
+import {TokenNamingContext} from './TokenNamingContext';
 import {
   registerEnglishFallback,
   useComponentTranslator,
@@ -309,6 +310,8 @@ export function Token({
   'data-testid': testId,
   'aria-labelledby': ariaLabelledBy,
   'aria-describedby': ariaDescribedBy,
+  'aria-haspopup': ariaHasPopup,
+  'aria-expanded': ariaExpanded,
   ref,
   ...rest
 }: TokenProps) {
@@ -319,6 +322,7 @@ export function Token({
   const t = useComponentTranslator();
   const LinkComponent = useLinkComponent();
   const role = useInteractiveRole({href, onClick, isDisabled});
+  const naming = use(TokenNamingContext);
 
   // When role is 'button' via context (no explicit onClick), treat as
   // if onClick was provided — the popover attaches its own handler.
@@ -327,7 +331,9 @@ export function Token({
   const removeButton = onRemove != null && (
     <button
       type="button"
-      aria-label={t('@astryx.token.remove', {label})}
+      aria-label={t('@astryx.token.remove', {
+        label: naming?.removeName ?? label,
+      })}
       onClick={e => {
         e.stopPropagation();
         onRemove(e);
@@ -352,12 +358,14 @@ export function Token({
     </>
   );
 
-  // Naming inputs reach the element that owns the token's action: the inner
-  // button of a clickable token, otherwise the root
+  // Naming and popup inputs reach the element that owns the token's action:
+  // the inner button of a clickable token, otherwise the root
   // (architecture:public-component-api INV5).
   const labellingProps = {
     'aria-labelledby': ariaLabelledBy,
     'aria-describedby': ariaDescribedBy,
+    'aria-haspopup': ariaHasPopup,
+    'aria-expanded': ariaExpanded,
   };
 
   const sharedProps = {
@@ -532,6 +540,7 @@ export function Token({
         <button
           type="button"
           onClick={effectiveOnClick}
+          aria-label={ariaLabelledBy == null ? naming?.actionName : undefined}
           {...labellingProps}
           aria-disabled={isDisabled || undefined}
           {...(isDisabled ? disabledInteractionProps() : null)}

package/src/Token/TokenNamingContext.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file TokenNamingContext.ts
+ * @input Naming parts from a caller whose token value renders outside its label
+ * @output Internal context: the names of a token's action and remove button
+ * @position Internal to Core; not exported from the Token entry point
+ */
+
+import {createContext} from 'react';
+
+/**
+ * Names for a Token whose visible text runs past its label. PowerSearch
+ * provides them: its tokens show the value as `endContent`.
+ *
+ * - `actionName` names a clickable token's inner button in place of `label`.
+ * - `removeName` names the remove button in place of `label`. The remove word
+ *   still comes from the catalog, so each locale keeps its word order.
+ */
+export interface TokenNaming {
+  actionName?: string;
+  removeName?: string;
+}
+
+export const TokenNamingContext = createContext<TokenNaming | null>(null);
+TokenNamingContext.displayName = 'TokenNamingContext';

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -292,6 +292,13 @@ export const docs = {
       type: 'CSSProperties',
       description: 'Inline styles for the visual control box.',
     },
+    {
+      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 its choices. popover is the inline combobox with its anchored suggestion menu. bottom-sheet replaces it with a trigger showing the selected tokens that opens one tall modal sheet: a search row on top, full-width checkbox rows that keep their place while the sheet is open, a Create row with hasCreate, and a footer pinned in every state with a confirmed Clear all and Save; the sheet edits a draft, so onChange fires once, when Save commits it, and a swipe, scrim or Escape close of a changed draft asks before discarding. adaptive uses the bottom sheet on compact touch screens and the popover otherwise, resolved the same way Selector resolves it. In the sheet presentation the trigger is the control (ref, id, aria-* and data-* reach it; with experimental passed, ref also accepts a Ref<HTMLInputElement | HTMLButtonElement> — an input-only ref still type-checks against that wider type, but with adaptive or bottom-sheet it receives the trigger button at runtime, so type the ref for both elements; TokenizerProps keeps its released ref type and gains only the optional experimental), and renderItem, renderToken, endContent, hasClear, hasEntriesOnFocus, menuWidth, tokenOverflowBehavior and hasAutoFocus have no surface to act on; the field warns once in development when they are passed. For example: <Tokenizer label=\"Tags\" searchSource={tagSource} value={tags} onChange={setTags} hasCreate experimental={{presentation: 'adaptive'}} />.",
+    },
   ],
   theming: {
     targets: [
@@ -631,6 +638,13 @@ export const docsZh = {
       type: 'CSSProperties',
       description: '可视控件框的内联样式。',
     },
+    {
+      name: 'experimental',
+      type: "{presentation?: 'popover' | 'bottom-sheet' | 'adaptive'}",
+      stability: 'experimental',
+      description:
+        "实验性选项：此对象中的任何内容都可能在补丁版本中更改或移除；省略它即保持稳定行为。presentation（默认 'popover'）决定字段如何呈现选项：popover 为内联组合框及其锚定建议菜单；bottom-sheet 改为一个显示已选标记的触发按钮，点按后打开一个高的模态底部面板——顶部为搜索行，下方为整行复选框行（面板打开期间位置保持不变），hasCreate 时有「创建」行，底部固定显示需确认的「全部清除」和「保存」；面板编辑的是草稿，onChange 仅在「保存」提交时触发一次，草稿有改动时滑动、点击遮罩或按 Escape 关闭会先询问是否放弃；adaptive 在紧凑触摸屏上使用底部面板，其他情况使用 popover，解析方式与 Selector 相同。在底部面板呈现中，触发按钮即为控件（ref、id、aria-* 和 data-* 都作用于它；传入 experimental 后，ref 也接受 Ref<HTMLInputElement | HTMLButtonElement>——仅为输入框类型的 ref 在这个更宽的类型下仍能通过类型检查，但在 adaptive 或 bottom-sheet 下运行时收到的是触发按钮，因此请为两种元素声明 ref 的类型；TokenizerProps 保留已发布的 ref 类型，仅新增可选的 experimental）；renderItem、renderToken、endContent、hasClear、hasEntriesOnFocus、menuWidth、tokenOverflowBehavior 和 hasAutoFocus 没有作用对象，传入时开发模式下会警告一次。例如：<Tokenizer label=\"标签\" searchSource={tagSource} value={tags} onChange={setTags} hasCreate experimental={{presentation: 'adaptive'}} />。",
+    },
   ],
   theming: {
     targets: [
@@ -830,5 +844,7 @@ export const docsDense = {
       'Icon at input start, before tokens. Icon name, SVG component, or ReactNode.',
     endContent: 'Content at input row end. For buttons, counts, controls.',
     handleRef: 'Imperative handle for focus() and blur() control.',
+    experimental:
+      "Experimental; may change in a patch. presentation: 'popover' (default, inline combobox) | 'bottom-sheet' (trigger + one searchable modal sheet of checkbox rows editing a draft that Save commits; onChange fires once, on Save) | 'adaptive' (sheet on compact touch, else popover).",
   },
 };