@astryxdesign/core 0.7.7-canary.4a8a76e → 0.7.7-canary.4e495ec

package/src/Selector/utils.ts

@@ -6,61 +6,15 @@
  * @position Utilities; used by Selector.tsx
  */
 
-import type {
-  SelectorOptionType,
-  SelectorOptionData,
-  SelectorDivider,
-  SelectorSection,
-} from './types';
+import type {SelectorOptionType, SelectorOptionData} from './types';
+import {getSelectableOptionEntries} from './selectableOptionEntries';
 
-/**
- * Type guard: check if option is a selectable option (string or OptionData)
- */
-export function isOptionData(
-  option: SelectorOptionType,
-): option is SelectorOptionData | string {
-  if (typeof option === 'string') {
-    return true;
-  }
-  return !('type' in option);
-}
-
-/**
- * Type guard: check if option is a divider
- */
-export function isDivider(
-  option: SelectorOptionType,
-): option is SelectorDivider {
-  return (
-    typeof option === 'object' && 'type' in option && option.type === 'divider'
-  );
-}
-
-/**
- * Type guard: check if option is a section
- */
-export function isSection(
-  option: SelectorOptionType,
-): option is SelectorSection {
-  return (
-    typeof option === 'object' && 'type' in option && option.type === 'section'
-  );
-}
-
-/**
- * Normalize string or option to consistent shape
- */
-export function normalizeOption(
-  option: string | SelectorOptionData,
-): SelectorOptionData {
-  if (typeof option === 'string') {
-    return {value: option, label: option};
-  }
-  return {
-    ...option,
-    label: option.label ?? option.value,
-  };
-}
+export {
+  isOptionData,
+  isDivider,
+  isSection,
+  normalizeOption,
+} from './optionShape';
 
 /**
  * Get all selectable options (flattening sections)
@@ -68,18 +22,5 @@ export function normalizeOption(
 export function getSelectableOptions(
   options: SelectorOptionType[],
 ): SelectorOptionData[] {
-  const result: SelectorOptionData[] = [];
-
-  for (const option of options) {
-    if (isOptionData(option)) {
-      result.push(normalizeOption(option));
-    } else if (isSection(option)) {
-      for (const opt of option.options) {
-        result.push(normalizeOption(opt));
-      }
-    }
-    // Skip dividers
-  }
-
-  return result;
+  return getSelectableOptionEntries(options).map(entry => entry.item);
 }

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/Switch/switchTouch.ts

@@ -4,8 +4,8 @@
  * @file switchTouch.ts
  * @input The UIKit switch constants (motion/uikit/switch.ts) and a track size
  * @output The pure model of Switch's touch presentation: thumb geometry, the
- *   drag's target, the flip rule, the commit on release and its click wait,
- *   and when the lifted thumb may settle
+ *   drag's target, the flip rule, the commit on release, and when the lifted
+ *   thumb may settle
  * @position Pure half of Switch's touch presentation; driven by
  *   useSwitchTouch.ts, tested by switchTouch.test.ts without a browser
  *
@@ -158,14 +158,6 @@ export function stepFlip(
   return isPast === flip.isArmed ? flip : {...flip, isArmed: isPast};
 }
 
-/**
- * Passive: how long a lift waits for the browser's own click before the
- * switch clicks its input itself, ms. The browser sends that click with the
- * lift's `touchend`. The surface's `touch-action` leaves no double-tap delay.
- * So this only runs out for a lift the browser does not count as a click.
- */
-export const BROWSER_CLICK_WAIT_MS = 300;
-
 /**
  * What a release commits: the side a drag flipped to; when nothing flipped,
  * the other side of the value, wherever the finger lifts. A press slid off

package/src/Switch/useSwitchTouch.ts

@@ -31,9 +31,9 @@ import {solveSpring, toSpring, type SpringDescription} from '../motion/spring';
 import {UIKIT_GESTURES} from '../motion/uikit/gestures';
 import {registerSwitchTable, switchControl} from '../motion/uikit/switch';
 import {useTouchPresentation} from '../utils/touchPresentation';
-import {armClickGuard, withoutClickGuard} from '../utils/clickGuard';
+import {awaitBrowserClick, clickForLift} from '../utils/browserClickWait';
+import {armClickGuard} from '../utils/clickGuard';
 import {
-  BROWSER_CLICK_WAIT_MS,
   commitOnRelease,
   dragTarget,
   settleTime,
@@ -253,11 +253,8 @@ export class SwitchTouchController {
   private isTracking = false;
   /** Which presentation the switch has: the touch one, or its own. */
   private presentation: SwitchPresentation = 'touch';
-  /** The press-time listeners under a fine pointer, while armed. */
-  private pressListeners: (() => void) | null = null;
-  private pressListenersTimer: ReturnType<typeof setTimeout> | null = null;
-  /** Passive: a lift is waiting for the browser's own click. */
-  private browserClickTimer: ReturnType<typeof setTimeout> | null = null;
+  /** Passive: a lift is waiting for the browser's own click; this ends it. */
+  private endBrowserClickWait: (() => void) | null = null;
   private reconcileTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(isOn: boolean, geometry: SwitchTouchGeometry) {
@@ -328,73 +325,7 @@ export class SwitchTouchController {
         }
       },
     });
-    // The lift's own click activates the input natively: the switch then
-    // clicks nothing itself.
-    const onClick = (event: MouseEvent) => {
-      if (event.isTrusted && this.browserClickTimer != null) {
-        clearTimeout(this.browserClickTimer);
-        this.browserClickTimer = null;
-        this.scheduleReconcile();
-      }
-    };
-    const listen = (): (() => void) => {
-      surface.addEventListener('click', onClick, true);
-      return () => {
-        surface.removeEventListener('click', onClick, true);
-      };
-    };
-    if (this.presentation === 'pointer') {
-      // Under a fine pointer only the press the host arms listens at rest.
-      // The switch's click listener comes with a press and goes after its
-      // click wait.
-      this.listenForPress = listen;
-      return [
-        host.attachConsumer(surface, tracker),
-        () => tracker.dispose(),
-        () => this.stopPressListeners(),
-      ];
-    }
-    return [
-      host.attachConsumer(surface, tracker),
-      () => tracker.dispose(),
-      listen(),
-    ];
-  }
-
-  /** Under a fine pointer: adds the switch's own listeners for a press. */
-  private listenForPress: (() => () => void) | null = null;
-
-  private startPressListeners(): void {
-    if (this.pressListenersTimer != null) {
-      clearTimeout(this.pressListenersTimer);
-      this.pressListenersTimer = null;
-    }
-    if (this.pressListeners == null && this.listenForPress != null) {
-      this.pressListeners = this.listenForPress();
-    }
-  }
-
-  /** The press's click window is over: its listeners go. */
-  private endPressListeners(afterMs: number): void {
-    if (this.pressListeners == null) {
-      return;
-    }
-    if (this.pressListenersTimer != null) {
-      clearTimeout(this.pressListenersTimer);
-    }
-    this.pressListenersTimer = setTimeout(() => {
-      this.pressListenersTimer = null;
-      this.stopPressListeners();
-    }, afterMs);
-  }
-
-  private stopPressListeners(): void {
-    if (this.pressListenersTimer != null) {
-      clearTimeout(this.pressListenersTimer);
-      this.pressListenersTimer = null;
-    }
-    this.pressListeners?.();
-    this.pressListeners = null;
+    return [host.attachConsumer(surface, tracker), () => tracker.dispose()];
   }
 
   /** Undo everything: listeners, timers, animations and inline styles. */
@@ -403,7 +334,6 @@ export class SwitchTouchController {
       detach();
     }
     this.detachers = [];
-    this.listenForPress = null;
     this.clearTimers();
     for (const animator of [this.thumb, this.fade, this.shadow]) {
       const element = animator?.element;
@@ -576,7 +506,6 @@ export class SwitchTouchController {
     switch (event) {
       case 'touchDown':
         this.isTracking = true;
-        this.startPressListeners();
         this.touchDown(time);
         return;
       case 'touchDragInside':
@@ -612,7 +541,6 @@ export class SwitchTouchController {
             byBrowserClick: true,
             clicksIfNoBrowserClick: touch.pointerType === 'touch',
           });
-          this.endPressListeners(BROWSER_CLICK_WAIT_MS);
           return;
         }
         if (
@@ -625,7 +553,6 @@ export class SwitchTouchController {
           // off toggles.
           this.released = true;
           this.abandon(time);
-          this.endPressListeners(0);
           return;
         }
         // A drag that flipped, or a press slid off and lifted outside, which
@@ -637,7 +564,6 @@ export class SwitchTouchController {
           armClickGuard(this.elements.input.ownerDocument);
         }
         this.release(time);
-        this.endPressListeners(0);
         return;
       case 'touchCancel':
         // The browser took the touch for its scroll, or a recognizer above
@@ -647,7 +573,6 @@ export class SwitchTouchController {
           this.released = true;
           this.abandon(time);
         }
-        this.endPressListeners(0);
         return;
       case 'touchDragEnter':
       case 'touchDragExit':
@@ -729,14 +654,23 @@ export class SwitchTouchController {
       this.showSide(commit, time, undefined, true);
     }
     this.pressEnded(time, true);
-    if (byBrowserClick) {
-      this.browserClickTimer = setTimeout(() => {
-        this.browserClickTimer = null;
-        if (clicksIfNoBrowserClick && commit !== this.isOn) {
-          this.clickInput();
-        }
-        this.scheduleReconcile();
-      }, BROWSER_CLICK_WAIT_MS);
+    const surface = this.elements?.surface;
+    if (byBrowserClick && surface != null) {
+      // The lift's own click activates the input natively: the switch then
+      // clicks nothing itself.
+      this.endBrowserClickWait = awaitBrowserClick(surface, {
+        onClicked: () => {
+          this.endBrowserClickWait = null;
+          this.scheduleReconcile();
+        },
+        onNoClick: () => {
+          this.endBrowserClickWait = null;
+          if (clicksIfNoBrowserClick && commit !== this.isOn) {
+            this.clickInput();
+          }
+          this.scheduleReconcile();
+        },
+      });
       return;
     }
     if (commit !== this.isOn) {
@@ -753,11 +687,9 @@ export class SwitchTouchController {
    */
   private clickInput(): void {
     const input = this.elements?.input;
-    if (input == null) {
-      return;
+    if (input != null) {
+      clickForLift(input);
     }
-    armClickGuard(input.ownerDocument);
-    withoutClickGuard(() => input.click());
   }
 
   /** If the owner kept the old value, the visuals go back to it. */
@@ -1038,10 +970,8 @@ export class SwitchTouchController {
   }
 
   private clearTimers(): void {
-    if (this.browserClickTimer != null) {
-      clearTimeout(this.browserClickTimer);
-      this.browserClickTimer = null;
-    }
+    this.endBrowserClickWait?.();
+    this.endBrowserClickWait = null;
     if (this.reconcileTimer != null) {
       clearTimeout(this.reconcileTimer);
       this.reconcileTimer = null;

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).",
   },
 };