@nxgt/material 3.41.0 → 3.42.0

package/docs/components/selection-and-choice.md

@@ -373,7 +373,7 @@ export function Framework() {
 
 ![Autocomplete](../previews/selection-choice-autocomplete.webp)
 
-Single or multiple (chips) autocomplete with free-solo values, accent-insensitive matching and a debounced server search.
+Single or multiple (chips) autocomplete with free-solo values, accent-insensitive matching and a debounced server search; a single value can be the input's own text (`display="text"`).
 
 ```tsx
 import { Autocomplete } from '@nxgt/material/components';
@@ -409,6 +409,8 @@ disabled with the field; Backspace in the empty input removes the last one.
 | Prop | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `mode` | `'single' \| 'multiple'` | — | required; decides the `value` type |
+| `display` | `'chip' \| 'text'` | `'chip'` | `mode="single"` only: how the value is drawn, a removable chip beside the input (and its placeholder), or the input's own text (type `AutocompleteDisplay`; see [One value as text](#one-value-as-text)). Ignored in `multiple` |
+| `clearable` | `boolean` | `true` | shows the "Clear" button; with `display="text"`, whether emptying the text and leaving the field clears the value |
 | `value` | `string` / `string[]` | — | required, per `mode` |
 | `onValueChange` | `(value?: string \| null) => void` / `(value?: string[] \| null) => void` | — | per `mode` |
 | `options` | `T[]` (`{ value, label, disabled? }` by default) | `[]` | the items (`disabled` on one: listed, announced as disabled, never picked); with `onSearch`, the list before a search and the selected options' labels |
@@ -435,6 +437,50 @@ An avatar in the rows and the chips:
 `getOptionLeading={(person) => <Avatar src={person.photo} alt="" />}`; see
 [the field look](../guides/field-look-2-x.md#autocomplete-and-the-chips-box).
 
+### One value as text
+
+By default a single value is drawn as a chip, like a multi-select with one
+entry. For picking one entry out of a long directory (a person, a place, a
+resource), `display="text"` makes the chosen option's label the input's own
+text, as a `Select` shows it, and keeps the search:
+
+```tsx
+<Autocomplete
+	mode="single"
+	display="text"
+	label="Member"
+	placeholder="Search a member"
+	options={selected ? [selected] : []}
+	onSearch={searchMembers}
+	value={value}
+	onValueChange={(next) => setValue(next ?? '')}
+/>
+```
+
+- The label fills the input (on the server too); the placeholder shows only
+  while the field is empty. The text is selected on focus, so typing replaces
+  it and searches again (`onSearch` or the local `filter`); the list opened on
+  the label is the whole `options`, not filtered by it.
+- Typing changes nothing until an option is picked. **Escape**, or leaving
+  the field (Tab, a click elsewhere), drops the typed text and brings the
+  label back; the value never moved. Escape on a closed list does the same
+  instead of clearing.
+- The "Clear" button empties the text and the value. Emptying the text by
+  hand and leaving the field clears the value too, since the field is
+  `clearable`. With `clearable={false}` there is no button, and an emptied text
+  gets the label back on leave: the value can only be replaced by another pick.
+- The option's `getOptionLeading` (or `renderSelectedLeading`) avatar shows
+  before the text while it is picked.
+- `freeSolo` still adds through its "Add" button; text left in the input and
+  not added is dropped on leave, as any other typed text.
+- Keep the selected option in `options` (as with `onSearch` and chips): a value
+  with no matching option has no label, so the input stays empty.
+- The input is the combobox: `aria-expanded` follows the list,
+  `aria-activedescendant` names the highlighted option, the picked option is
+  `aria-selected`, and the field's live region announces the suggestions as
+  before. `AutocompleteFormField` takes `display` and `clearable` too. Leaving the
+  window (Alt-Tab) is not leaving the field: the typed text waits.
+
 ### Searching a server
 
 `onSearch` takes the query and an `AbortSignal`; hand the signal to `fetch`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.41.0",
+	"version": "3.42.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"