@astryxdesign/core 0.7.5 → 0.7.6-canary.0135af4

package/src/Typeahead/BaseTypeahead.doc.mjs

@@ -107,7 +107,8 @@ export const docs = {
     {
       name: 'searchSource',
       type: 'SearchSource<T>',
-      description: 'Data source providing search and bootstrap methods.',
+      description:
+        '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,
     },
     {
@@ -175,7 +176,7 @@ export const docs = {
       name: 'isFocusableDisabled',
       type: 'boolean',
       description:
-        'Keep a disabled input focusable with aria-disabled and readOnly so a caller-owned disabled reason remains discoverable. It blocks text entry, but when applied after results are already open, Enter can still select the highlighted option.',
+        'Keep a disabled input focusable with aria-disabled and readOnly so a caller-owned disabled reason remains discoverable. It blocks text entry, opening the results and picking a result, also from results that were open before it applied; Escape or Tab still closes them.',
       default: 'false',
     },
     {
@@ -188,7 +189,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',
     },
     {
@@ -267,7 +268,8 @@ export const docsZh = {
     {
       name: 'searchSource',
       type: 'SearchSource<T>',
-      description: '提供搜索和引导方法的数据源。',
+      description:
+        '提供搜索和引导方法的数据源。`search(query, context)` 可调用 `context.update(items)` 先显示已有的匹配项；返回值是最终列表，同一查询在第一个列表之后的每个列表都保留已显示的行，并只在其后追加新行。',
       required: true,
     },
     {
@@ -334,7 +336,7 @@ export const docsZh = {
       name: 'isFocusableDisabled',
       type: 'boolean',
       description:
-        '使用 aria-disabled 和只读状态保持禁用输入框可聚焦，以便访问调用方提供的禁用原因。它会阻止文本输入，但如果结果已打开，按 Enter 仍可选择高亮选项。',
+        '使用 aria-disabled 和只读状态保持禁用输入框可聚焦，以便访问调用方提供的禁用原因。它会阻止文本输入、打开结果列表和选择结果，在它生效前已打开的结果中也是如此；Escape 或 Tab 仍可关闭列表。',
       default: 'false',
     },
     {
@@ -346,7 +348,8 @@ export const docsZh = {
     {
       name: 'debounceMs',
       type: 'number',
-      description: '触发搜索前的防抖延迟（毫秒）。同步数据源设置为 0。',
+      description:
+        '触发搜索前的防抖延迟（毫秒）。同步数据源，以及通过 `context.update` 显示本地匹配项并自行延迟服务器请求的数据源，设置为 0。',
       default: '150',
     },
     {
@@ -467,7 +470,7 @@ export const docsDense = {
     emptySearchText: 'Content when the query matched nothing. ReactNode.',
     isDisabled: 'Whether input disabled.',
     isFocusableDisabled:
-      'Keeps disabled input focusable and blocks text entry; an already-open highlight can still be selected with Enter.',
+      'Keeps disabled input focusable; blocks text entry, opening and picking, also from an already-open list (Escape/Tab close it).',
     hasAutoFocus: 'Auto-focus on mount.',
     debounceMs: 'Search debounce ms. 0 for sync.',
     size: 'Dropdown option padding size.',

package/src/Typeahead/BaseTypeahead.spec.md

@@ -77,34 +77,34 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept         | Closed values or states                  | Meaning                                                      | Availability by state      | Default                          | Owner                        | Stability | Invalid-value behavior                                                                   |
-| --------------- | ---------------------------------------- | ------------------------------------------------------------ | -------------------------- | -------------------------------- | ---------------------------- | --------- | ---------------------------------------------------------------------------------------- |
-| selection       | `T` or `null`                            | Caller-controlled selected result                            | all states                 | required                         | `component:BaseTypeahead`    | released  | caller retains control                                                                   |
-| search source   | `search`, `bootstrap`, optional `cancel` | Supplies query and focus results                             | enabled input              | required                         | `component:BaseTypeahead`    | released  | rejected work clears current results                                                     |
-| focus bootstrap | on or off                                | Offers bootstrap results before query input                  | empty focused input        | off                              | `component:BaseTypeahead`    | released  | off keeps the menu closed                                                                |
-| query threshold | non-negative number                      | Minimum visible-character count before search                | non-empty query            | `1`                              | `component:BaseTypeahead`    | released  | below threshold cancels work and closes results                                          |
-| debounce        | milliseconds                             | Delays query search                                          | typed query                | `150`                            | `component:BaseTypeahead`    | released  | non-positive runs immediately                                                            |
-| result cap      | number                                   | Limits fetched results shown                                 | completed search/bootstrap | `10`                             | `component:BaseTypeahead`    | released  | source order is preserved                                                                |
-| result content  | default, `renderItem`, or `item.element` | Chooses content inside the stable option row                 | result present             | default TypeaheadItem            | caller and component         | released  | `item.element` takes precedence                                                          |
-| disabled state  | native or focusable-disabled             | Blocks query mutation; native disabled blocks all activation | disabled                   | native disabled                  | component and caller wrapper | released  | an already-open focusable-disabled list can still select with Enter (retained violation) |
-| popup width     | intrinsic or fixed pixels                | Sets result popup width before viewport clamping             | popup present              | intrinsic, at least anchor width | `component:BaseTypeahead`    | released  | viewport fit wins                                                                        |
-| size            | `sm`, `md`, `lg`                         | Selects option-row padding                                   | popup options              | `md`                             | `component:BaseTypeahead`    | released  | TypeScript rejects other values                                                          |
+| Concept         | Closed values or states                  | Meaning                                                      | Availability by state      | Default                          | Owner                        | Stability | Invalid-value behavior                                                          |
+| --------------- | ---------------------------------------- | ------------------------------------------------------------ | -------------------------- | -------------------------------- | ---------------------------- | --------- | ------------------------------------------------------------------------------- |
+| selection       | `T` or `null`                            | Caller-controlled selected result                            | all states                 | required                         | `component:BaseTypeahead`    | released  | caller retains control                                                          |
+| search source   | `search`, `bootstrap`, optional `cancel` | Supplies query and focus results                             | enabled input              | required                         | `component:BaseTypeahead`    | released  | rejected work clears current results                                            |
+| focus bootstrap | on or off                                | Offers bootstrap results before query input                  | empty focused input        | off                              | `component:BaseTypeahead`    | released  | off keeps the menu closed                                                       |
+| query threshold | non-negative number                      | Minimum visible-character count before search                | non-empty query            | `1`                              | `component:BaseTypeahead`    | released  | below threshold cancels work and closes results                                 |
+| debounce        | milliseconds                             | Delays query search                                          | typed query                | `150`                            | `component:BaseTypeahead`    | released  | non-positive runs immediately                                                   |
+| result cap      | number                                   | Limits fetched results shown                                 | completed search/bootstrap | `10`                             | `component:BaseTypeahead`    | released  | source order is preserved                                                       |
+| result content  | default, `renderItem`, or `item.element` | Chooses content inside the stable option row                 | result present             | default TypeaheadItem            | caller and component         | released  | `item.element` takes precedence                                                 |
+| disabled state  | native or focusable-disabled             | Blocks query mutation; native disabled blocks all activation | disabled                   | native disabled                  | component and caller wrapper | released  | a list open before focusable-disabled applied picks nothing and can still close |
+| popup width     | intrinsic or fixed pixels                | Sets result popup width before viewport clamping             | popup present              | intrinsic, at least anchor width | `component:BaseTypeahead`    | released  | viewport fit wins                                                               |
+| size            | `sm`, `md`, `lg`                         | Selects option-row padding                                   | popup options              | `md`                             | `component:BaseTypeahead`    | released  | TypeScript rejects other values                                                 |
 
 ## Behavioral and layout contract
 
 Draft requirements identify their observational or current-authority basis.
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                           | Basis                                                 | Draft review state                             |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
-| FR1 | The input is controlled by internal query state while `value` is caller-controlled; selecting a result calls `onChange(item)`, clears query/results, closes the popup, and returns focus to the input.                                                        | Current source and tests                              | verified shipped behavior                      |
-| FR2 | Search starts only at the grapheme-count threshold, uses the configured debounce, and never presents an empty result for a query that was not searched.                                                                                                       | Public API, current i18n character utility, tests     | verified audit remediation                     |
-| FR3 | A newer query, selection, clear, source replacement, or unmount invalidates stale asynchronous work. Escape hides the current popup but does not invalidate pending work, so a late response currently reopens it (retained violation).                       | Current source, focused retained-red probe, and tests | verified shipped behavior                      |
-| FR4 | The popup is a named listbox whose result rows are options. A completed empty search renders one disabled option so the listbox retains a valid owned child.                                                                                                  | APG combobox pattern, axe, tests                      | verified audit remediation                     |
-| FR5 | Arrow keys wrap the highlight; Home/End move to the first/last option; Enter selects; Escape and Tab hide the current popup; IME-owned key events do not activate combobox commands. Escape dismissal is not durable while source work remains pending (FR3). | Current source and tests                              | verified shipped behavior; Escape gap retained |
-| FR6 | Pending asynchronous source work sets `aria-busy` and renders one named Spinner unless the composed wrapper owns the busy indicator lane.                                                                                                                     | Current source, input-family FR7, tests               | verified shipped behavior                      |
-| FR7 | Supported BaseProps DOM, ARIA, data, class, style, event, and `xstyle` inputs reach the combobox input while component-owned role, state, value, and behavior remain authoritative.                                                                           | `architecture:public-component-api/INV5–INV7`, tests  | verified audit remediation                     |
-| FR8 | The popup remains within the inline viewport at 320 CSS px, including long default results and a requested width larger than the available viewport.                                                                                                          | WCAG 1.4.10, real Chromium                            | verified audit remediation                     |
-| FR9 | Native disabled removes ordinary focus and activation. Focusable-disabled uses `aria-disabled` plus `readOnly` and blocks text/query mutation, but applying it after the popup opens does not currently block Enter selection (retained violation).           | Current source, tests, and focused retained-red probe | verified shipped behavior                      |
+| ID  | Candidate invariant                                                                                                                                                                                                                                                                                        | Basis                                                 | Draft review state                             |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
+| FR1 | The input is controlled by internal query state while `value` is caller-controlled; selecting a result calls `onChange(item)`, clears query/results, closes the popup, and returns focus to the input.                                                                                                     | Current source and tests                              | verified shipped behavior                      |
+| FR2 | Search starts only at the grapheme-count threshold, uses the configured debounce, and never presents an empty result for a query that was not searched.                                                                                                                                                    | Public API, current i18n character utility, tests     | verified audit remediation                     |
+| FR3 | A newer query, selection, clear, source replacement, or unmount invalidates stale asynchronous work. Escape hides the current popup but does not invalidate pending work, so a late response currently reopens it (retained violation).                                                                    | Current source, focused retained-red probe, and tests | verified shipped behavior                      |
+| FR4 | The popup is a named listbox whose result rows are options. A completed empty search renders one disabled option so the listbox retains a valid owned child.                                                                                                                                               | APG combobox pattern, axe, tests                      | verified audit remediation                     |
+| FR5 | Arrow keys wrap the highlight; Home/End move to the first/last option; Enter selects; Escape and Tab hide the current popup; IME-owned key events do not activate combobox commands. Escape dismissal is not durable while source work remains pending (FR3).                                              | Current source and tests                              | verified shipped behavior; Escape gap retained |
+| FR6 | Pending asynchronous source work sets `aria-busy` and renders one named Spinner unless the composed wrapper owns the busy indicator lane.                                                                                                                                                                  | Current source, input-family FR7, tests               | verified shipped behavior                      |
+| FR7 | Supported BaseProps DOM, ARIA, data, class, style, event, and `xstyle` inputs reach the combobox input while component-owned role, state, value, and behavior remain authoritative.                                                                                                                        | `architecture:public-component-api/INV5–INV7`, tests  | verified audit remediation                     |
+| FR8 | The popup remains within the inline viewport at 320 CSS px, including long default results and a requested width larger than the available viewport.                                                                                                                                                       | WCAG 1.4.10, real Chromium                            | verified audit remediation                     |
+| FR9 | Native disabled removes ordinary focus and activation. Focusable-disabled uses `aria-disabled` plus `readOnly` and blocks text/query mutation, opening the list, and selection by Enter or a press, including from a list that was open before it applied; that list can still close (`spec:AST-085` FR2). | Current source and tests                              | verified shipped behavior                      |
 
 ### Allowed variation
 
@@ -116,17 +116,17 @@ Draft requirements identify their observational or current-authority basis.
 
 ### Representative states
 
-| State             | Required invariant                                                                                                                    | Allowed variation                      |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
-| rest              | named combobox is closed and not busy                                                                                                 | caller-owned wrapper and label         |
-| focused bootstrap | popup opens only when enabled and results exist                                                                                       | synchronous or asynchronous source     |
-| query pending     | combobox is busy and duplicate stale work is rejected                                                                                 | direct or wrapper-owned Spinner        |
-| results           | one highlighted option and valid active descendant                                                                                    | grouped/default/custom content         |
-| completed empty   | one disabled empty option; no active descendant                                                                                       | caller-supplied empty text             |
-| selected result   | matching option exposes `aria-selected=true`                                                                                          | generic check presentation             |
-| disabled          | native disabled blocks activation; focusable-disabled blocks query mutation but can still select an already-open highlight with Enter | native or focusable-disabled semantics |
-| dismissed pending | Escape hides the popup; a late pending response currently reopens it                                                                  | source completion timing               |
-| narrow viewport   | popup and result content remain inside two viewport gutters                                                                           | intrinsic or requested width           |
+| State             | Required invariant                                                                                                               | Allowed variation                      |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| rest              | named combobox is closed and not busy                                                                                            | caller-owned wrapper and label         |
+| focused bootstrap | popup opens only when enabled and results exist                                                                                  | synchronous or asynchronous source     |
+| query pending     | combobox is busy and duplicate stale work is rejected                                                                            | direct or wrapper-owned Spinner        |
+| results           | one highlighted option and valid active descendant                                                                               | grouped/default/custom content         |
+| completed empty   | one disabled empty option; no active descendant                                                                                  | caller-supplied empty text             |
+| selected result   | matching option exposes `aria-selected=true`                                                                                     | generic check presentation             |
+| disabled          | native disabled blocks activation; focusable-disabled blocks query mutation, opening and picking, also from an already-open list | native or focusable-disabled semantics |
+| dismissed pending | Escape hides the popup; a late pending response currently reopens it                                                             | source completion timing               |
+| narrow viewport   | popup and result content remain inside two viewport gutters                                                                      | intrinsic or requested width           |
 
 ### Transformation and precedence order
 
@@ -237,17 +237,17 @@ Draft requirements identify their observational or current-authority basis.
 
 ## Verification map
 
-| Contract        | Verification                                           | Representative states                             | Mutation or failure expectation                                        | Audit section                    |
-| --------------- | ------------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------- |
-| FR1–FR2         | BaseTypeahead and Typeahead tests                      | query, overlap, select, clear                     | current work replaces newer results or selection does not close        | `audit:BaseTypeahead/behavior`   |
-| FR3             | shared stale-response tests plus retained-red probe    | newer query, clear, unmount, Escape while pending | late work replaces current results or reopens after explicit dismissal | `audit:BaseTypeahead/a11y`       |
-| FR4, AR1–AR4    | focused tests, component-scoped axe, live-region tests | results, empty, busy, selected                    | invalid listbox ownership or state/announcement disappears             | `audit:BaseTypeahead/a11y`       |
-| FR5, AR5        | keyboard, focus-out, IME, and retained-red tests       | arrows, Home/End, Enter, Escape, Tab, composition | command selects or dismisses at the wrong time                         | `audit:BaseTypeahead/a11y`       |
-| FR6             | busy-lane tests                                        | direct and composed pending source                | duplicate/missing Spinner or stale busy state                          | `audit:BaseTypeahead/a11y`       |
-| FR7             | focused passthrough tests and strict lint              | native-only, alias collisions, DOM/style/events   | supported consumer input is dropped or owned semantics are replaced    | `audit:BaseTypeahead/api`        |
-| FR8             | real-Chromium 320px sensor receipt                     | long result, wide request, LTR/RTL                | popup or its content crosses either viewport gutter                    | `audit:BaseTypeahead/responsive` |
-| FR9             | shared disabled tests plus retained-red probe          | native disabled, focusable-disabled after open    | disabled mode mutates query or accepts an already-open selection       | `audit:BaseTypeahead/a11y`       |
-| Theming anatomy | knowledge and theming-target checks                    | all mapped parts                                  | target inventory or disposition drifts                                 | `audit:BaseTypeahead/theming`    |
+| Contract        | Verification                                           | Representative states                                     | Mutation or failure expectation                                        | Audit section                    |
+| --------------- | ------------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------- |
+| FR1–FR2         | BaseTypeahead and Typeahead tests                      | query, overlap, select, clear                             | current work replaces newer results or selection does not close        | `audit:BaseTypeahead/behavior`   |
+| FR3             | shared stale-response tests plus retained-red probe    | newer query, clear, unmount, Escape while pending         | late work replaces current results or reopens after explicit dismissal | `audit:BaseTypeahead/a11y`       |
+| FR4, AR1–AR4    | focused tests, component-scoped axe, live-region tests | results, empty, busy, selected                            | invalid listbox ownership or state/announcement disappears             | `audit:BaseTypeahead/a11y`       |
+| FR5, AR5        | keyboard, focus-out, IME, and retained-red tests       | arrows, Home/End, Enter, Escape, Tab, composition         | command selects or dismisses at the wrong time                         | `audit:BaseTypeahead/a11y`       |
+| FR6             | busy-lane tests                                        | direct and composed pending source                        | duplicate/missing Spinner or stale busy state                          | `audit:BaseTypeahead/a11y`       |
+| FR7             | focused passthrough tests and strict lint              | native-only, alias collisions, DOM/style/events           | supported consumer input is dropped or owned semantics are replaced    | `audit:BaseTypeahead/api`        |
+| FR8             | real-Chromium 320px sensor receipt                     | long result, wide request, LTR/RTL                        | popup or its content crosses either viewport gutter                    | `audit:BaseTypeahead/responsive` |
+| FR9             | shared disabled tests                                  | native disabled; focusable-disabled before and after open | disabled mode mutates query, opens the list, or accepts a selection    | `audit:BaseTypeahead/a11y`       |
+| Theming anatomy | knowledge and theming-target checks                    | all mapped parts                                          | target inventory or disposition drifts                                 | `audit:BaseTypeahead/theming`    |
 
 ## Decision log