Suggestion Card

import { Canvas, Controls, Meta, Title } from '@storybook/addon-docs/blocks';

import * as SuggestionCardStories from './SuggestionCard.stories';

<Meta of={SuggestionCardStories} name='Usage' />

<Title />

## Purpose

Shows changes an agent suggests, and lets the user decide what to do with them.

## Usage

Use it inside an agent message in a chat, when the agent proposes a change and waits for the user.

- The content area is a slot (`children`); what goes in it is up to the screen. `SuggestionChange` is an optional helper for the before and after case: the field name over its before and after values, with the "Before" and "After" headings and a dash for an empty value passed in so they can be translated.
- Put the decision buttons in `actions`. The reference has Accept (primary), Refine (secondary) and Dismiss (subtle).
- While `state` is `pending` the actions show. When the user accepts, set `state` to `accepted` and pass `statusLabel`; it replaces the actions and is announced to screen readers.
- `buttonSize` (`xs` by default, or `s`) sets the size of the whole button set in `actions`, so the buttons always match. It applies to every PDS `Button` in `actions`.
- `padding` takes the same options as `Panel` (`none`, `condensed`, `standard`, `spacious`). It defaults to `condensed`, which suits a card in a chat.
- The title is a heading. Set `headingLevel` so it fits the page outline, and `headingSize` (`m` by default, or `l`) for how large it looks. They are separate: the level is the tag, the size is the type.
- It is a decision prompt for the message stream. A full-width report on a page is a Panel with an agentic border, not this component.

## Implementation

See the table below for the available props. The other stories show a worked example of changes, the accepted state, an interactive version and the card inside a chat message.

<hr />

<Canvas of={SuggestionCardStories.Default} />
<Controls of={SuggestionCardStories.Default} />