@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Typeahead/Typeahead.doc.mjs

@@ -119,7 +119,7 @@ export const docs = {
       name: 'searchSource',
       type: 'SearchSource<T>',
       description:
-        'Data source providing search and bootstrap methods for populating the dropdown.',
+        'Data source providing search and bootstrap methods. `search(query, context)` may call `context.update(items)` to show matches it already has before it returns; the value it returns is the final list, and every list after the first for a query keeps the shown rows first and adds new rows after them.',
       required: true,
     },
     {
@@ -154,14 +154,15 @@ export const docs = {
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Disables the input.',
+      description:
+        'Disables the input. The field keeps its tab stop: it is announced as disabled (aria-disabled), is read-only, and opens and picks nothing.',
       default: 'false',
     },
     {
       name: 'disabledMessage',
       type: 'string',
       description:
-        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Typeahead in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.',
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus, and the reason describes the field (activation stays blocked). Use this instead of wrapping a disabled Typeahead in Tooltip, so the reason is attached to the field itself.',
     },
     {
       name: 'maxMenuItems',
@@ -246,7 +247,7 @@ export const docs = {
       name: 'debounceMs',
       type: 'number',
       description:
-        'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
+        'Debounce delay in ms before triggering search. Set to 0 for synchronous sources, and for a source that shows local matches through `context.update` and delays its own server request.',
       default: '150',
     },
     {
@@ -279,12 +280,14 @@ export const docs = {
     {
       name: 'containerClassName',
       type: 'string',
-      description: 'Class name for the field container. Same targeting as `containerXstyle`.',
+      description:
+        'Class name for the field container. Same targeting as `containerXstyle`.',
     },
     {
       name: 'containerStyle',
       type: 'CSSProperties',
-      description: 'Inline styles for the field container. Same targeting as `containerXstyle`.',
+      description:
+        'Inline styles for the field container. Same targeting as `containerXstyle`.',
     },
     {
       name: 'controlXstyle',
@@ -332,6 +335,11 @@ export const docs = {
         description:
           'Add a search delay for remote data sources to avoid excessive network requests.',
       },
+      {
+        guidance: true,
+        description:
+          'For a remote source, show the matches the page already has at once: call `context.update(local)` in `search`, pass `debounceMs={0}`, delay the server request in the source, and return the server answer with the shown rows first.',
+      },
       {
         guidance: true,
         description:
@@ -381,6 +389,11 @@ export const docsZh = {
         description:
           'Add a search delay for remote data sources to avoid excessive network requests.',
       },
+      {
+        guidance: true,
+        description:
+          'For a remote source, show the matches the page already has at once: call `context.update(local)` in `search`, pass `debounceMs={0}`, delay the server request in the source, and return the server answer with the shown rows first.',
+      },
       {
         guidance: false,
         description:
@@ -427,6 +440,11 @@ export const docsDense = {
         description:
           'Add a search delay for remote data sources to avoid excessive network requests.',
       },
+      {
+        guidance: true,
+        description:
+          'For a remote source, show the matches the page already has at once: call `context.update(local)` in `search`, pass `debounceMs={0}`, delay the server request in the source, and return the server answer with the shown rows first.',
+      },
       {
         guidance: true,
         description:

package/src/Typeahead/Typeahead.tsx

@@ -46,7 +46,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {Token} from '../Token';
 import {useTooltip} from '../Tooltip';
@@ -69,14 +68,22 @@ import {
   type FieldInputBaseProps,
   useFieldInputStyling,
 } from '../Field/fieldParts';
+import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
 import type {SizeValue} from '../utils/types';
 import type {SearchableItem, SearchSource} from './types';
 import {themeProps} from '../utils/themeProps';
-import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
+import {
+  registerEnglishFallback,
+  useComponentTranslator,
+} from '../i18n/useComponentTranslator';
+import english from '../i18n/generated-english/Typeahead/Typeahead.generated';
+
+registerEnglishFallback(english);
 export type {
   InputStatus as TypeaheadStatus,
   InputStatusType as TypeaheadStatusType,
@@ -116,7 +123,7 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<
    * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
    * @default 'attached'
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
   /**
    * Icon to display at the start of the input.
    * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -166,17 +173,21 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<
    * @default 'No results found'
    */
   emptySearchText?: ReactNode;
-  /** Whether the input is disabled. @default false */
+  /**
+   * Whether the input is disabled. A disabled field keeps its tab stop: it is
+   * announced as disabled (`aria-disabled`), is read-only, and opens and
+   * picks nothing.
+   * @default false
+   */
   isDisabled?: boolean;
   /**
    * Explains why the input is disabled. When set together with `isDisabled`,
    * the input shows a tooltip with this text on hover and keyboard focus, and
-   * the field stays focusable (via `aria-disabled`) so the reason is
-   * discoverable by keyboard and assistive technology. Editing and selection
-   * stay blocked.
+   * the reason describes the field for assistive technology. Editing and
+   * selection stay blocked.
    *
-   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled input in `Tooltip`, so the reason
+   * is attached to the field itself.
    *
    * @example
    * ```
@@ -427,7 +438,7 @@ export function Typeahead<T extends SearchableItem>({
     containerClassName,
     containerStyle,
   });
-  const t = useTranslator();
+  const t = useComponentTranslator();
   const size = useSize(sizeProp, 'md');
   const generatedInputId = useId();
   const inputId = idProp ?? generatedInputId;
@@ -444,10 +455,9 @@ export function Typeahead<T extends SearchableItem>({
   const inputRef = useRef<HTMLInputElement>(null);
   const tokenRef = useRef<HTMLElement>(null);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the input wrapper (which already exists) and
-  // the input stays perceivable via aria-disabled + readOnly instead of the
-  // disabled attribute. Editing and selection stay blocked by the isDisabled
+  // Disabled-reason tooltip. The tooltip listeners attach to the input wrapper
+  // (which already exists); a disabled input stays perceivable via
+  // aria-disabled + readOnly instead of the disabled attribute. Editing and selection stay blocked by the isDisabled
   // guards (handleWrapperClick, handleEnterEditMode, and BaseTypeahead's own
   // focus/change guards).
   const showsDisabledMessage = isDisabled && !!disabledMessage;
@@ -649,6 +659,7 @@ export function Typeahead<T extends SearchableItem>({
             status && !isDisabled && inputStatusHoverShadowStyles[status.type],
             status && inputStatusFocusWithinStyles[status.type],
             isDisabled && inputWrapperStyles.disabled,
+            isDisabled && inputDisabledFocusStyles.nestedRing,
             inputGroup && groupStyles.inGroup,
             controlXstyle,
           ),
@@ -709,7 +720,8 @@ export function Typeahead<T extends SearchableItem>({
                 emptySearchText={emptySearchText}
                 isDisabled={isDisabled}
                 hasAutoFocus={hasAutoFocus}
-                isFocusableDisabled={showsDisabledMessage}
+                // A disabled field keeps its tab stop (spec:AST-085 FR1).
+                isFocusableDisabled={isDisabled}
                 inputId={inputId}
                 ariaDescribedBy={
                   [ariaDescribedByProp, ariaDescribedBy]

package/src/Typeahead/TypeaheadItem.doc.mjs

@@ -6,7 +6,8 @@ export const docs = {
   name: 'TypeaheadItem',
   subComponentOf: 'Typeahead',
   displayName: 'Typeahead Item',
-  description: 'Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.',
+  description:
+    'Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.',
   props: [
     {
       name: 'item',
@@ -50,7 +51,8 @@ export const docs = {
 export const docsZh = {
   name: 'TypeaheadItem',
   displayName: 'Typeahead Item',
-  description: '预输入结果的默认下拉项渲染器。显示标签以及可选的图标、描述和头像。导出供自定义 renderItem 实现使用。',
+  description:
+    '预输入结果的默认下拉项渲染器。显示标签以及可选的图标、描述和头像。导出供自定义 renderItem 实现使用。',
   props: [
     {
       name: 'item',
@@ -85,7 +87,8 @@ export const docsZh = {
 export const docsDense = {
   name: 'TypeaheadItem',
   displayName: 'Typeahead Item',
-  description: 'Default dropdown item renderer. Label w/ optional icon, description, avatar. Exported for custom renderItem.',
+  description:
+    'Default dropdown item renderer. Label w/ optional icon, description, avatar. Exported for custom renderItem.',
   propDescriptions: {
     item: 'Search result item to render.',
     icon: 'Icon/avatar before label.',

package/src/Typeahead/committedChoicesKey.tsx

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file committedChoicesKey.tsx
+ * @input React context
+ * @output Exports CommittedChoicesKeyContext and useCommittedChoices
+ * @position Package-internal; not exported from the package entry point.
+ *   Tokenizer passes a key for its committed values through it, and whether
+ *   those values reached its limit. When the key changes while the list is
+ *   open, BaseTypeahead reloads the list, so a committed value leaves it and a
+ *   removed one returns (component:Tokenizer FR13, spec:AST-092 FR4); at the
+ *   limit it closes the list instead (FR15). A source that is only rebuilt in
+ *   render does not change the key and reloads nothing.
+ */
+
+import {createContext, use} from 'react';
+
+export type CommittedChoices = {
+  /** Changes exactly when the committed values change. */
+  key: string;
+  /** The committed values' ids: never offered as choices. */
+  ids: ReadonlySet<string>;
+  /** No further value can be committed, so no list is offered. */
+  isAtLimit: boolean;
+};
+
+export const CommittedChoicesKeyContext = createContext<
+  CommittedChoices | undefined
+>(undefined);
+CommittedChoicesKeyContext.displayName = 'CommittedChoicesKeyContext';
+
+/** The caller's committed values, if a caller provides them. */
+export function useCommittedChoices(): CommittedChoices | undefined {
+  return use(CommittedChoicesKeyContext);
+}

package/src/Typeahead/index.ts

@@ -12,7 +12,7 @@
  */
 
 // Shared types
-export type {SearchableItem, SearchSource} from './types';
+export type {SearchableItem, SearchContext, SearchSource} from './types';
 
 // Search source utilities
 export {createStaticSource} from './createStaticSource';

package/src/Typeahead/types.ts

@@ -60,6 +60,25 @@ export interface SearchableItem<TAuxData = unknown> {
   auxiliaryData?: TAuxData;
 }
 
+/**
+ * Per-call context a typeahead passes as the second argument of
+ * `SearchSource.search` (`spec:AST-092`).
+ */
+export interface SearchContext<T extends SearchableItem = SearchableItem> {
+  /**
+   * Show a list for this query before `search()` settles, such as matches the
+   * page already holds while the server is still answering.
+   *
+   * Every list is the source's complete answer at that moment. The first list
+   * shown for a query may replace the rows; every later list for the same
+   * query, including the value `search()` returns, keeps the rows already
+   * shown first and in order and adds new rows only after them. An empty list
+   * leaves the shown rows in place. Calls for a query that is no longer
+   * current, or after `search()` settles, are ignored.
+   */
+  update(items: T[]): void;
+}
+
 /**
  * Search source interface for providing items to typeahead components.
  * Supports both synchronous and asynchronous search.
@@ -93,13 +112,18 @@ export interface SearchableItem<TAuxData = unknown> {
  */
 export interface SearchSource<T extends SearchableItem = SearchableItem> {
   /**
-   * Called on query change. Returns matching items.
-   * Can be synchronous or asynchronous.
+   * Called on query change. Returns matching items: the final, complete list
+   * for the query. Can be synchronous or asynchronous.
+   *
+   * A typeahead that can show partial lists passes `context`; call
+   * `context.update(items)` to show a list before returning, for example local
+   * matches first and the server's answer appended after them. Callers that
+   * cannot show partial lists omit `context` and show only the return value.
    *
    * For expensive operations (API calls, large datasets), consider caching
    * results internally to avoid redundant work on repeated queries.
    */
-  search(query: string): Promise<T[]> | T[];
+  search(query: string, context?: SearchContext<T>): Promise<T[]> | T[];
 
   /**
    * Called on init/focus. Returns initial/default items.