@astryxdesign/core 0.7.7-canary.c0929c8 → 0.7.7-canary.c19ca12

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,
@@ -193,6 +194,8 @@ const styles = stylex.create({
     borderRadius: radiusVars['--radius-full'],
     width: '16px',
     height: '16px',
+    // A token cut by its width shrinks only its label, not the button.
+    flexShrink: 0,
     color: 'inherit',
     '::after': {
       content: '""',
@@ -307,6 +310,8 @@ export function Token({
   'data-testid': testId,
   'aria-labelledby': ariaLabelledBy,
   'aria-describedby': ariaDescribedBy,
+  'aria-haspopup': ariaHasPopup,
+  'aria-expanded': ariaExpanded,
   ref,
   ...rest
 }: TokenProps) {
@@ -317,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.
@@ -325,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);
@@ -350,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 = {
@@ -530,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).",
   },
 };

package/src/Tokenizer/Tokenizer.tsx

@@ -6,16 +6,10 @@
  * @file Tokenizer.tsx
  * @input Uses React, BaseTypeahead, Field, Token, useAnnounce,
  *   useAdaptivePresentation, and TokenizerBottomSheet (lazy)
- * @output Exports Tokenizer multi-select typeahead component, and the
- *   internal TokenizerWithPresentation signature the `internal/tokenizer-presentation`
- *   entry re-exports
+ * @output Exports Tokenizer multi-select typeahead component
  * @position Composed component; forwards DOM ref and exposes focus control via
- *   handleRef. The sheet presentation — a trigger that opens
- *   TokenizerBottomSheet — is implemented but not exposed: `TokenizerProps`
- *   offers no `experimental.presentation` while its user experience is being
- *   finished (`component:Tokenizer` DEC-3, implementation gap), and only
- *   Astryx's own packages reach it through the internal entry
- *   (`architecture:react-component-runtime` INV13).
+ *   handleRef. The experimental `presentation` option swaps the inline
+ *   combobox for a trigger that opens TokenizerBottomSheet.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Tokenizer/index.ts
@@ -55,6 +49,7 @@ import {
 import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {TokenizerClearAllMessageContext} from './TokenizerClearAllMessageContext';
+import {TokenizerItemRemovableContext} from './TokenizerItemRemovableContext';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {useAdaptivePresentation} from '../hooks/useAdaptivePresentation';
 import {useIsHydrating} from '../hooks/useIsHydrating';
@@ -95,6 +90,7 @@ import {composeEventHandlers, mergeProps} from '../utils';
 import {joinAriaIDs} from '../utils/inputAria';
 import {isFocusDetached} from '../utils/focusReturn';
 import {themeProps} from '../utils/themeProps';
+import type {SheetDraftChange} from '../internal/sheetDraft';
 import type {TokenizerBottomSheetProps} from './TokenizerBottomSheet';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
@@ -147,36 +143,6 @@ export interface TokenizerHandle {
   blur(): void;
 }
 
-/**
- * The presentation options the sheet-capable signature admits. Not public:
- * `TokenizerProps` has no `experimental` while the sheet's user experience is
- * being finished; Astryx's own packages reach the sheet through
- * `@astryxdesign/core/internal/tokenizer-presentation`.
- */
-export interface TokenizerPresentationOptions {
-  /**
-   * How the field presents its choices.
-   * - `'popover'`: the inline combobox with its anchored suggestion menu —
-   *   the stable behavior.
-   * - `'bottom-sheet'`: 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 with a confirmed Clear all and Done. Suited
-   *   to compact touch screens, where the inline combobox competes with the
-   *   software keyboard.
-   * - `'adaptive'`: the bottom sheet on compact coarse-pointer screens,
-   *   otherwise the popover — the same resolution Selector uses.
-   *
-   * In the sheet presentation the trigger is the control: `ref`, `id`,
-   * `aria-*`, and `data-*` reach it. `renderItem`, `renderToken`,
-   * `endContent`, `hasClear`, `hasEntriesOnFocus`, `menuWidth`,
-   * `tokenOverflowBehavior`, and `hasAutoFocus` have no surface to act on
-   * and warn once in development.
-   * @default 'popover'
-   */
-  presentation?: 'popover' | 'bottom-sheet' | 'adaptive';
-}
-
 export interface TokenizerProps<T extends SearchableItem> extends Omit<
   FieldInputBaseProps<HTMLInputElement>,
   'onChange' | 'onFocus' | 'onBlur' | 'onKeyDown'
@@ -334,26 +300,58 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   ref?: React.Ref<HTMLInputElement>;
   /** Imperative handle ref for focus/blur control. */
   handleRef?: React.Ref<TokenizerHandle>;
+  /**
+   * Experimental options, outside the stable compatibility promise: anything
+   * in this object may change or be removed in a patch release. Omit it for
+   * the stable behavior.
+   * @experimental
+   */
+  experimental?: {
+    /**
+     * How the field presents its choices.
+     * - `'popover'`: the inline combobox with its anchored suggestion menu —
+     *   the stable behavior.
+     * - `'bottom-sheet'`: 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: `onChange` fires once, when Save
+     *   commits it, and a swipe, scrim or Escape close of a changed draft asks
+     *   before discarding. Suited to compact touch screens, where the inline
+     *   combobox competes with the software keyboard.
+     * - `'adaptive'`: the bottom sheet on compact coarse-pointer screens,
+     *   otherwise the popover — the same resolution Selector uses.
+     *
+     * In the sheet presentation the trigger is the control: `ref`, `id`,
+     * `aria-*`, and `data-*` reach it. `renderItem`, `renderToken`,
+     * `endContent`, `hasClear`, `hasEntriesOnFocus`, `menuWidth`,
+     * `tokenOverflowBehavior`, and `hasAutoFocus` have no surface to act on
+     * and warn once in development.
+     * @experimental
+     * @default 'popover'
+     */
+    presentation?: 'popover' | 'bottom-sheet' | 'adaptive';
+  };
 }
 
 /**
- * The props of the sheet-capable signature: `TokenizerProps` plus the
- * presentation options and a `ref` that also accepts the sheet presentation's
- * trigger button, the control it stands for there. Not public: reached only
- * as `TokenizerWithPresentation` through the internal entry, so the released
- * `TokenizerProps` — an interface, so `interface X extends TokenizerProps<T>`,
- * `Omit<TokenizerProps<T>, …>` and `ComponentProps<typeof Tokenizer>` keep
- * their released shapes — names no presentation.
+ * The props the experimental opt-in admits. `experimental` is present, and
+ * `ref` also accepts the sheet presentation's trigger button, the control it
+ * stands for there. Only the overload below reaches this type. `TokenizerProps`
+ * stays the component's declared props type: it is an interface, so
+ * `interface X extends TokenizerProps<T>`, `Omit<TokenizerProps<T>, …>` and
+ * `ComponentProps<typeof Tokenizer>` keep their released shapes.
  */
-export type TokenizerWithPresentationProps<T extends SearchableItem> = Omit<
+type TokenizerExperimentalProps<T extends SearchableItem> = Omit<
   TokenizerProps<T>,
-  'ref'
+  'ref' | 'experimental'
 > & {
-  /** How the field presents its choices; see `TokenizerPresentationOptions`. */
-  experimental?: TokenizerPresentationOptions;
+  /** @experimental */
+  experimental: NonNullable<TokenizerProps<T>['experimental']>;
   /**
    * Ref forwarded to the control: the combobox input in the popover
    * presentation, the trigger button in the sheet presentation.
+   * @experimental
    */
   ref?: React.Ref<HTMLInputElement | HTMLButtonElement>;
 };
@@ -723,10 +721,13 @@ function EndLane({
   );
 }
 
-// The public signature names no presentation: `ComponentProps<typeof
-// Tokenizer>` and every public call resolve against `TokenizerProps`. The
-// implementation also reads the presentation options, reached only through
-// `TokenizerWithPresentation` below.
+// Keep this overload first. TypeScript resolves `ComponentProps<typeof
+// Tokenizer>` against the last overload, so that type stays the stable props.
+// A call that passes `experimental` matches this one and may pass the wider
+// `ref`.
+export function Tokenizer<T extends SearchableItem>(
+  props: TokenizerExperimentalProps<T>,
+): React.JSX.Element;
 export function Tokenizer<T extends SearchableItem>(
   props: TokenizerProps<T>,
 ): React.JSX.Element;
@@ -780,7 +781,7 @@ export function Tokenizer<T extends SearchableItem>({
   'aria-describedby': ariaDescribedByProp,
   'aria-labelledby': ariaLabelledByProp,
   ...restProps
-}: TokenizerWithPresentationProps<T>): React.JSX.Element {
+}: TokenizerProps<T> | TokenizerExperimentalProps<T>): React.JSX.Element {
   const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const {rest, container} = useFieldInputStyling('Tokenizer', restProps, {
     containerXstyle,
@@ -843,6 +844,17 @@ export function Tokenizer<T extends SearchableItem>({
     },
     [onChangeQuery],
   );
+  // Save's one report. The sheet announced each edit as it happened, so
+  // nothing is announced here; a field that is disabled at Save reports
+  // nothing.
+  const handleSheetCommit = useCallback(
+    (items: T[], change: SheetDraftChange<T>) => {
+      if (!isDisabled) {
+        onChange(items, change);
+      }
+    },
+    [isDisabled, onChange],
+  );
   // Set around a focus move the field makes itself — a presentation swap
   // handing focus from one control to the other — so the receiving control
   // does not report it as focus entering from outside.
@@ -1008,11 +1020,18 @@ export function Tokenizer<T extends SearchableItem>({
   // `endContent`, a clear button, or all three — so its width is measured
   // rather than assumed, and the input reserves it.
   const [laneRef, laneReserve] = useEndLaneReserve(END_LANE_INSET);
+  // A composing component can lock tokens (PowerSearch's read-only filters
+  // and read-only field). No remove path removes a locked token.
+  const isItemRemovable = use(TokenizerItemRemovableContext);
+  const canRemoveItem = useCallback(
+    (item: T) => isItemRemovable?.(item) ?? true,
+    [isItemRemovable],
+  );
   // The half of the lane's contents this component knows about. The busy half
   // is the leaf's own business — folding it in here would mean reading the
   // busy state during this render, which is exactly the re-render the store
   // exists to avoid.
-  const hasClearButton = hasClear && value.length > 0 && !isDisabled;
+  const hasClearButton = hasClear && !isDisabled && value.some(canRemoveItem);
   const hasStaticEndLane = Boolean(endContent || hasClearButton);
   const [isFocusedWithin, setIsFocusedWithin] = useState(false);
   const isTruncated =
@@ -1264,7 +1283,7 @@ export function Tokenizer<T extends SearchableItem>({
   // announcement covers both.
   const handleRemove = useCallback(
     (item: T, options?: {silent?: boolean}): boolean => {
-      if (isDisabled) {
+      if (isDisabled || !canRemoveItem(item)) {
         return false;
       }
       const newItems = value.filter(v => v.id !== item.id);
@@ -1275,22 +1294,25 @@ export function Tokenizer<T extends SearchableItem>({
       inputRef.current?.focus();
       return true;
     },
-    [value, onChange, isDisabled, announce, t],
+    [value, onChange, isDisabled, canRemoveItem, announce, t],
   );
 
-  // Handle clearing all items
   // A composing component that words its own Clear all (PowerSearch) provides
   // its words; otherwise the field's own (component:Tokenizer AR7).
   const clearAllMessage =
     use(TokenizerClearAllMessageContext) ?? t('@astryx.tokenizer.allRemoved');
   const handleClearAll = useCallback(
     (options?: {silent?: boolean}) => {
-      if (isDisabled || value.length === 0) {
+      const removedItems = value.filter(canRemoveItem);
+      if (isDisabled || removedItems.length === 0) {
         return;
       }
-      // Report the last item as removed (convention)
-      const lastItem = value[value.length - 1];
-      onChange([], {item: lastItem, type: 'remove'});
+      // onChange names one item. Clear all names the last one it removes.
+      const lastRemovedItem = removedItems[removedItems.length - 1];
+      onChange(
+        value.filter(item => !canRemoveItem(item)),
+        {item: lastRemovedItem, type: 'remove'},
+      );
       // Focus moves to the input, so the emptied selection is announced, in
       // the sheet's words (WCAG 4.1.3). The sheet announces its own Clear all.
       if (!options?.silent) {
@@ -1298,7 +1320,7 @@ export function Tokenizer<T extends SearchableItem>({
       }
       inputRef.current?.focus();
     },
-    [value, onChange, isDisabled, announce, clearAllMessage],
+    [value, onChange, isDisabled, canRemoveItem, announce, clearAllMessage],
   );
 
   // Handle backspace on empty input — remove last token
@@ -1361,7 +1383,7 @@ export function Tokenizer<T extends SearchableItem>({
         key={item.id}
         label={item.label}
         size={size}
-        onRemove={isDisabled ? undefined : onRemoveItem}
+        onRemove={isDisabled || !canRemoveItem(item) ? undefined : onRemoveItem}
         isDisabled={isDisabled}
         xstyle={styles.token}
       />
@@ -1706,15 +1728,13 @@ export function Tokenizer<T extends SearchableItem>({
               label={label}
               searchSource={searchSource}
               value={value}
-              isAtMax={isAtMax}
+              maxEntries={maxEntries}
               hasCreate={hasCreate}
               maxMenuItems={maxMenuItems ?? 10}
               minQueryLength={minQueryLength ?? 1}
               debounceMs={debounceMs ?? 150}
               emptySearchText={emptySearchText}
-              onAdd={handleAdd}
-              onRemove={handleRemove}
-              onClearAll={() => handleClearAll({silent: true})}
+              onCommit={handleSheetCommit}
               onChangeQuery={handleSheetQueryChange}
             />
           )}
@@ -1821,19 +1841,3 @@ export function Tokenizer<T extends SearchableItem>({
 }
 
 Tokenizer.displayName = 'Tokenizer';
-
-/**
- * The same component with the sheet presentation reachable: `experimental`
- * (`presentation: 'popover' | 'bottom-sheet' | 'adaptive'`) and a `ref` that
- * also takes the trigger button. Not public — re-exported only by
- * `@astryxdesign/core/internal/tokenizer-presentation`, the entry reserved
- * for Astryx's own packages (`architecture:react-component-runtime` INV13),
- * while the sheet's user experience is being finished (`component:Tokenizer`
- * DEC-3). The public `Tokenizer` renders the popover presentation for every
- * field.
- */
-export const TokenizerWithPresentation = Tokenizer as <
-  T extends SearchableItem,
->(
-  props: TokenizerWithPresentationProps<T>,
-) => React.JSX.Element;