Loading…

AI Suggested Value

An AI-proposed value for any form control, pending until accepted and marked afterwards.

AI
1 file
No extra npm packages
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add ai-suggested-value

No npm packages are needed beyond what Dowel already requires.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { SuggestedValue } from "@/components/ui/ai-suggested-value";

Examples

Every example the tests run, live and operable, side by side.

Default
Wired
On ASelect
Low Confidence
Arriving

API

Generated from the component's own types, so a prop cannot appear here without existing.

<SuggestedValue>

Prop	Type	Default
`label` (required) The field, for the buttons' names: "Accept suggestion — Company".	`string`	—
`onAccept` (required)	`(value: T, suggestion: Suggestion<T>) => void`	—
`children` (required) The control. Receives the description, and any id or ARIA a FormControl passes down.	`ReactElement<Record<string, unknown>>`	—
`announce` Announce a suggestion when it arrives. Off by default: a form that fills twenty fields at once would narrate all twenty, and the description on the control already tells a reader when they reach the field.	`boolean`	`false`
`aria-describedby`	`string`	—
`aria-invalid`	`ComponentPropsWithRef<"input">["aria-invalid"]`	—
`equals` How to compare values. Object.is by default.	`(a: T, b: T) => boolean`	`Object.is`
`id`	`string`	—
`lowConfidenceBelow` Confidence below this is called low, in words.	`number`	`0.7`
`onDismiss`	`(suggestion: Suggestion<T>) => void`	—
`onRevert` Called with the value the field held before the fill, so it can be put back.	`(previous: T \| undefined) => void`	—
`status` Supply to own the status; otherwise it is kept here.	`SuggestionStatus`	—
`suggestion` Null or undefined offers nothing. A different suggestion starts pending again.	`Suggestion<T> \| null`	—
`value` The control's current value. Lets the marker say the fill was edited since, and lets Undo restore what the field held before.	`T`	—

Plus every attribute of <div> except children, id, aria-describedby, aria-invalid.

Accessibility

The suggestion is the control's description, so a reader who lands on the field hears it without any announcement — and announcing is opt-in, because a form filling twenty fields at once would narrate all twenty. The row that holds it is rendered from the start and never display:none, so when announcing is on, a suggestion arriving after mount is actually heard. Each button's name carries the field it belongs to, so a page of Accepts is a page of different buttons. Provenance and confidence are words with a number, never a colour. Acceptance is reported, not performed: the control is the consumer's, so its value, its label and its own keyboard behaviour are untouched — there is no shortcut hijacked from a select or a date field. The id and ARIA a FormControl passes down are forwarded to the control, and an existing aria-describedby is merged rather than replaced.

Quality

Measured from the source and its tests at build time.

All scores

10/10

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — passes
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — passes
No fixed widths — passes

Prop

Type

Default

label

The field, for the buttons' names: "Accept suggestion — Company".

string

—

onAccept

(value: T, suggestion: Suggestion<T>) => void

—

children

The control. Receives the description, and any id or ARIA a FormControl passes down.

ReactElement<Record<string, unknown>>

—

announce

Announce a suggestion when it arrives. Off by default: a form that fills twenty fields at once would narrate all twenty, and the description on the control already tells a reader when they reach the field.

boolean

false

aria-describedby

string

—

aria-invalid

ComponentPropsWithRef<"input">["aria-invalid"]

—

equals

How to compare values. Object.is by default.

(a: T, b: T) => boolean

Object.is

id

string

—

lowConfidenceBelow

Confidence below this is called low, in words.

number

0.7

onDismiss

(suggestion: Suggestion<T>) => void

—

onRevert

Called with the value the field held before the fill, so it can be put back.

(previous: T | undefined) => void

—

status

Supply to own the status; otherwise it is kept here.

SuggestionStatus

—

suggestion

Null or undefined offers nothing. A different suggestion starts pending again.

Suggestion<T> | null

—

value

The control's current value. Lets the marker say the fill was edited since, and lets Undo restore what the field held before.

T

—