@astryxdesign/core 0.7.7-canary.f9ac85f → 0.7.7

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
@@ -96,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';
@@ -148,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'
@@ -335,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>;
 };
@@ -724,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;
@@ -781,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,
@@ -844,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.
@@ -1009,9 +1020,8 @@ 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 field).
-  // Backspace and the token remove controls skip a locked token. Clear all
-  // does not check it.
+  // 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,
@@ -1021,7 +1031,7 @@ export function Tokenizer<T extends SearchableItem>({
   // 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 =
@@ -1287,19 +1297,22 @@ export function Tokenizer<T extends SearchableItem>({
     [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) {
@@ -1307,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
@@ -1370,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}
       />
@@ -1715,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}
             />
           )}
@@ -1830,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;