Documentation standard

## Documentation completeness checklist

### Required sections

- [ ] 1. Frontmatter complete (status, version, deps, category)
- [ ] 2. Overview (1 paragraph: what + when to use + when NOT to use)
- [ ] 3. Interactive Preview / Code tabs at the top via `<ComponentPreview>` (real source, copyable, never duplicated)
- [ ] 4. Anatomy — subcomponent **hierarchy tree** (a `├─` code block of the real component names), present in BOTH the Storybook autodocs (`## Anatomy` in the story `meta` JSDoc) AND this Fumadocs page
- [ ] 5. Installation (complete CLI command)
- [ ] 6. Basic usage (minimal runnable example)
- [ ] 7. API Reference — inputs (all, with type, default, description)
- [ ] 8. API Reference — outputs (all, with payload type, when fired)
- [ ] 9. API Reference — slots / content projection / children
- [ ] 10. API Reference — imperative API (if any)
- [ ] 11. API Reference — exported types / interfaces
- [ ] 12. All variants with interactive preview
- [ ] 13. All visual states with preview
- [ ] 14. Composition with AI SDK (end-to-end)
- [ ] 15. Composition with a second AI integration (alternative)
- [ ] 16. Composition with framework-native primitives (no AI framework)
- [ ] 17. Keyboard shortcuts (table)
- [ ] 18. ARIA roles and labels documented
- [ ] 19. Screen reader notes (NVDA + VoiceOver tested)
- [ ] 20. WCAG level stated (AA minimum)
- [ ] 21. CSS variables — ALL listed per layer (semantic + AI-specific) with defaults
- [ ] 22. Tailwind classes consumed (which utilities)
- [ ] 23. Design decisions — at least 1 ADR linked
- [ ] 24. Component changelog
- [ ] 25. Known issues / limitations

### Quality bar

- [ ] Every code example IS runnable (copy + paste works)
- [ ] Every interactive preview lets you edit inputs
- [ ] No "TODO", "TBD", or "coming soon" in the public text
- [ ] Consistent language across the page (one of PT-BR or EN-US)
- [ ] Obscure technical terms have a glossary

apps/docs/content/components/
+-- prompt-input.mdx                    container
+-- prompt-input-textarea.mdx           each subcomponent gets its own page
+-- prompt-input-toolbar.mdx
+-- prompt-input-tools.mdx
+-- prompt-input-button.mdx
+-- prompt-input-submit.mdx
+-- prompt-input-attachments.mdx
+-- prompt-input-attachment.mdx
+-- prompt-input-action-menu.mdx
+-- prompt-input-model-select.mdx

---
title: PromptInput
description: Prompt input container with state machine and form behaviour.
component: prompt-input
status: stable # stable | preview | deprecated
version: 0.1.0
since: 0.1.0
category: AI / Chatbot
dependencies:
  - '@gremorie/ng-core'
related:
  - prompt-input-textarea
  - prompt-input-toolbar
  - prompt-input-submit
---

# PromptInput

## Overview

> **What it is.** Container for prompt entry in AI interfaces. Manages the
> state machine (ready / submitted / streaming / error), keyboard shortcuts,
> attachments, and subcomponent coordination.
>
> **When to use.** Any conversational interface where the user types prompts.
>
> **When NOT to use.** Structured inputs (traditional forms, search bars).
> For existing conversation messages, use Message instead.

## Preview

<PromptInputPreview />

## Anatomy

A **hierarchy tree** of the real subcomponent names. The SAME tree must also
live in the component's Storybook `meta` JSDoc under a `## Anatomy` heading
(it renders in the autodocs Docs tab), so the two surfaces never drift.

\`\`\`
<prompt-input>
+-- <prompt-input-attachments> (optional)
| +-- <prompt-input-attachment>
+-- <prompt-input-textarea> (required)
+-- <prompt-input-toolbar> (optional, recommended)
+-- <prompt-input-tools>
| +-- <prompt-input-button>
+-- <prompt-input-submit>
\`\`\`

## Installation

\`\`\`bash
npx gremorie add ng-prompt-input
\`\`\`

Installs all subcomponents of the PromptInput family.

Prerequisites:

- Tailwind CSS v4
- @gremorie/ng-core installed
- Framework-specific peer deps (Angular 21+ for NG edition; React 19+ for RX)

The CLI verifies prerequisites and offers to install what's missing.

## Basic usage

[Minimal runnable example — imports complete, props minimal]

## API Reference

### Inputs / Props

| Name    | Type                   | Default      | Description                     |
| ------- | ---------------------- | ------------ | ------------------------------- |
| `value` | `Signal<string>`       | `signal('')` | Two-way binding via `[(value)]` |
| `state` | `PromptInputState`     | `'ready'`    | State machine value             |
| `size`  | `'sm' \| 'md' \| 'lg'` | `'md'`       | Visual size                     |
| ...     | ...                    | ...          | ...                             |

### Outputs / Events

| Name          | Payload                  | Fires when            |
| ------------- | ------------------------ | --------------------- |
| `valueChange` | `string`                 | Every textarea change |
| `submit`      | `PromptInputSubmitEvent` | User submits          |
| ...           | ...                      | ...                   |

### Slots / Children

| Slot    | Accepts                                     | Required          |
| ------- | ------------------------------------------- | ----------------- |
| Default | Textarea, Toolbar, Attachments in any order | At least textarea |

### Imperative API

| Method    | Returns | Description                    |
| --------- | ------- | ------------------------------ |
| `focus()` | `void`  | Focus the textarea             |
| `clear()` | `void`  | Clear textarea and attachments |

### Exported types

\`\`\`ts
export type PromptInputState = 'ready' | 'submitted' | 'streaming' | 'error';

export interface PromptInputSubmitEvent {
value: string;
attachments: File[];
preventDefault: () => void;
}
\`\`\`

## Variants

### Size

[Preview grid: sm / md / lg]

### Variant

[Preview grid: default / ghost / bordered]

### Position

[Demo: static vs sticky-bottom in scrollable container]

### Disabled

[Preview disabled state]

## States

### Ready

Initial state. User can type and submit.

### Submitted

Message sent, waiting for LLM response.

### Streaming

Receiving LLM chunks. Submit becomes a cancel button.

### Error

Last submission failed. Submit becomes a retry button.

## Compositions

### With AI SDK

[Full 30-50 line example with useChat]

### With framework-native primitives

[Example with fetch + ReadableStream]

### Edge cases

- Toolbar-less (textarea + inline submit)
- Sticky bottom in scrollable container
- Forced multi-line (textarea always expanded)
- Read-only during streaming (controlled disabled)

## Accessibility

### Keyboard shortcuts

| Key             | Action                                           | Configurable |
| --------------- | ------------------------------------------------ | ------------ |
| `Enter`         | Submit (if `submitOnEnter=true`)                 | Yes          |
| `Shift + Enter` | Newline in textarea                              | No           |
| `Mod + Enter`   | Force submit                                     | No           |
| `Esc`           | Clear OR cancel streaming (state-dependent)      | No           |
| `Mod + K`       | Global focus                                     | Yes          |
| `Tab`           | Navigation through textarea -> toolbar -> submit | No           |

### ARIA

| Element       | Role / Attribute | Value                                                  |
| ------------- | ---------------- | ------------------------------------------------------ |
| Container     | `role`           | `"form"`                                               |
| Container     | `aria-label`     | `"AI prompt input"` (configurable)                     |
| Submit button | `aria-label`     | varies by state: "Send", "Submitting", "Stop", "Retry" |
| Live region   | `aria-live`      | `"polite"` for state changes                           |

### Screen reader

Tested in NVDA + Firefox, NVDA + Chrome, VoiceOver + Safari, VoiceOver iOS +
Safari Mobile.

Announcements:

- Submit fires: "Message submitted"
- Streaming starts: "AI is responding"
- Streaming ends: "Response complete"
- Error: "Submission failed. Press to retry."

### WCAG

**Level AA guaranteed.**

- Contrast: AA in every state (verified with axe-core)
- Touch targets: 44x44px minimum on mobile
- Focus visible: always, via `:focus-visible`
- Reduced motion: respected in all animations
- Zoom 200%: layout intact

## Theming

### CSS variables consumed

All colours and radii come from variables. Zero hardcoded values. Gremorie
uses a two-tier system (primitives -> semantics). Components consume
**semantics only**.

[Table listing every CSS variable this component consumes]

### Tailwind classes consumed

To change behaviour without editing CSS vars, edit the classes in the
component file:

| Subcomponent   | Key classes                                               |
| -------------- | --------------------------------------------------------- |
| Container      | `flex flex-col gap-2 rounded-md border bg-background p-3` |
| Textarea       | `min-h-[2.5rem] max-h-[12rem] resize-none bg-transparent` |
| Submit (ready) | `bg-primary text-primary-foreground`                      |
| ...            | ...                                                       |

### Customisation

Registry model: you own the code. Edit the files in
`src/app/gremorie/prompt-input/` (NG) or `src/components/gremorie/prompt-input/`
(RX) directly. No theme API. More power, but requires care during future
upstream updates (use the registry diff workflow).

## Design decisions

- [ADR-006 — State machine vs reactive state](/adr/006-state-machine)
- [ADR-007 — Slot-based vs prop-driven](/adr/007-slots-vs-props)
- [ADR-011 — Monolithic component (no Brain/Helm split)](/adr/011-monolithic)
- [ADR-013 — CSS variables two-tier](/adr/013-two-tier-tokens)

## Changelog

### 0.1.0 — initial release

- Container with state machine
- States: `ready | submitted | streaming | error`
- Two-way binding via signal / state
- Drag-and-drop attachments
- Image paste
- Global `Mod + K` shortcut
- WCAG AA

## Known issues

- `field-sizing: content` not supported in Firefox < 124. Falls back to
  `ResizeObserver` automatically; minimal flicker on rapid typing.
- Image paste doesn't work in Safari < 16.4 (Clipboard API limitation).
- In SSR mode (Analog for NG, RSC for RX), the focus shortcut activates
  only after full hydration.

## See also

- [`<prompt-input-textarea>`](./prompt-input-textarea) — auto-expand textarea
- [`<prompt-input-submit>`](./prompt-input-submit) — submit with states
- [AI SDK integration guide](/integrations/ai-sdk)