@gradeui/ui 3.2.0 → 4.0.0

package/components/ui/button.md

@@ -2,15 +2,16 @@
 name: Button
 import: "@gradeui/ui"
 variants: [default, destructive, outline, secondary, ghost, link, raised]
-sizes: [sm, md, lg, icon]
+sizes: [2xs, xs, sm, md, lg]
 props:
   - variant? (default | destructive | outline | secondary | ghost | link | raised) — `raised` here is a back-compat alias (the raised TRAIT on a neutral key surface); prefer the `raised` prop
   - raised?: boolean — presence TRAIT: tactile elevation (bevel + drop + hover glow + pressed sink) layered onto ANY variant — raised primary, raised outline, etc. Glow tone reads --btn-glow → --accent-glow → --selected-glow; override per-button via style={{ "--btn-glow": "var(--warning)" }}
-  - size? (sm | md | lg | icon) — t-shirt scale aligned with Tabs/ToggleGroup heights (sm=h-7, md=h-8, lg=h-10). `default` still works as an alias for `md`.
+  - size? (2xs | xs | sm | md | lg) — t-shirt scale aligned with Tabs/ToggleGroup heights (2xs=h-5, xs=h-6, sm=h-7, md=h-8, lg=h-10). 2xs/xs are the dense tool-panel sizes (match Figma Button size=2xs/xs). `default` still works as an alias for `md`.
+  - iconOnly?: boolean — squares the button at the current `size` height (w = h, no horizontal padding) for icon-only buttons; the icon child is centered. This is THE way to make a square icon button at any density (sm→28², 2xs→20²).
   - asChild?: boolean — renders as the child element (use to wrap <a>/<Link>)
   - disabled?: boolean
   - All native button HTML attrs (onClick, type, etc.)
-when_to_use: Any clickable action. Use size="icon" for square icon-only buttons, variant="link" for inline links that should look like Button, the `raised` prop for high-commitment / weighty actions where the chrome can afford a tactile "physical key" treatment (composes with any variant; variant="raised" remains the neutral-key alias). A Button placed next to a TabsList of the same size lines up edge-to-edge without per-call overrides.
+when_to_use: Any clickable action. Use `iconOnly` for square icon-only buttons (at any size), variant="link" for inline links that should look like Button, the `raised` prop for high-commitment / weighty actions where the chrome can afford a tactile "physical key" treatment (composes with any variant; variant="raised" remains the neutral-key alias). A Button placed next to a TabsList of the same size lines up edge-to-edge without per-call overrides.
 composes_with: [Dialog, DropdownMenu, Tooltip, Card (in CardFooter), Row, Form controls]
 aliases: [button, push button, plain button, bordered button, destructive button, capsule button, link button, action button, cta, raised button, pill button, key button]
 ---
@@ -18,7 +19,8 @@ aliases: [button, push button, plain button, bordered button, destructive button
 ```jsx
 <Button>Save</Button>
 <Button variant="outline" size="sm">Cancel</Button>
-<Button size="icon" variant="ghost"><Mail /></Button>
+<Button iconOnly variant="ghost"><Mail /></Button>
+<Button size="sm" iconOnly variant="outline"><Plus /></Button>
 ```
 
 ```jsx

package/components/ui/color-picker.md

@@ -0,0 +1,34 @@
+---
+name: ColorPicker
+import: "@gradeui/ui"
+props:
+  - value?: string | null — a Grade colour token NAME ("action/primary"), the literal "transparent", or null when nothing is picked
+  - onValueChange?: (value: string | null) => void — fired with the next value (token name, "transparent", or null)
+  - tokens?: { group, tokens }[] — token families offered in the list; defaults to the Grade semantic set (surface / action / status)
+  - searchable?: boolean — show the search input (default true)
+  - triggerVariant? (default | inline) — default = form-control surface (swatch + name); inline = just a clickable swatch for inspector / fill-row use
+  - placeholder?: string — trigger text when nothing is selected
+  - searchPlaceholder?: string — search-input placeholder
+  - emptyMessage?: string — shown when search returns no rows
+  - allowTransparent?: boolean — include a Transparent option at the top (default true)
+  - align? (start | center | end) — popover alignment (default start)
+  - disabled?: boolean — lock to a read-only display of the current value
+when_to_use: The token-led single-select colour picker — the focused "pick one colour token" sibling of FillPicker's solid tab. Use it anywhere a value is ONE Grade colour token (a fill colour, a border colour, an accent override) rather than a full paint. Composes Popover + Command exactly like Combobox, but each row is a Swatch + the token's short name, grouped by family and searchable. triggerVariant="inline" reduces the trigger to a single clickable swatch — reach for that inside inspectors and the FillSection fill rows. For a full paint (gradient / image / shader) use FillPicker; for a list of fills use FillSection; for a multi-stop gradient use GradientEditor.
+composes_with: [Popover, Command, Swatch, FillSection, GradientEditor, Field, PropertyList]
+aliases: [color picker, colour picker, token picker, colour token picker, color token picker, swatch picker, paint colour, fill colour picker, accent picker, colour dropdown]
+---
+
+```jsx
+// Token-led colour field.
+<ColorPicker value={color} onValueChange={setColor} />
+```
+
+```jsx
+// Inline swatch trigger — the inspector / fill-row affordance.
+<ColorPicker
+  triggerVariant="inline"
+  value={stopColor}
+  onValueChange={setStopColor}
+  aria-label="Stop colour"
+/>
+```

package/components/ui/fill-picker.md

@@ -1,12 +1,16 @@
 ---
 name: FillPicker
 import: "@gradeui/ui"
+subcomponents: [FillSection]
 props:
   - value: FillValue — current paint ({ type, color?, gradient?, src?, fit?, repeat?, tileSize?, preset?, palette?, postPreset?, opacity? }) (required)
   - onChange: (value: FillValue) => void — called on any change (required)
-when_to_use: Grade's paint picker — the control for choosing a frame's background fill, modelled on Figma's fill popover. A fill-type icon row (solid · gradient · image · pattern · video · shader) switches the panel below; a global opacity sits at the foot. Emits a FillValue that maps 1:1 onto BackgroundFill props. This is a Studio/inspector chrome control — pair it with BackgroundFill, which renders the chosen paint. Not for app content.
-composes_with: [BackgroundFill (renders the FillValue), Popover (host it in a popover), ShaderPresetPicker (the shader tab), the inspector Fill section]
-aliases: [fill picker, paint picker, background picker, fill chooser, fill popover]
+  - FillSection: value — FillValue[] — the ordered list of fills to stack as rows
+  - FillSection: onChange — (value: FillValue[]) => void — fired with the next list on add / edit / remove / visibility toggle
+  - FillSection: title?: string — section heading (default "Fills")
+when_to_use: Grade's paint picker — the control for choosing a frame's background fill, modelled on Figma's fill popover. A fill-type icon row (solid · gradient · image · pattern · video · shader) switches the panel below; a global opacity sits at the foot. Emits a FillValue that maps 1:1 onto BackgroundFill props. This is a Studio/inspector chrome control — pair it with BackgroundFill, which renders the chosen paint. Not for app content. Use the FillSection subcomponent to edit a LIST of fills (the Figma "Fill" inspector section): each row is a Solid/Gradient/Image toggle, the matching value control (ColorPicker / GradientEditor popover / image URL), an opacity %, a visibility eye, and a remove button, with an add button in the header.
+composes_with: [BackgroundFill (renders the FillValue), Popover (host it in a popover), ColorPicker (the solid value), GradientEditor (the gradient value), ShaderPresetPicker (the shader tab), the inspector Fill section]
+aliases: [fill picker, paint picker, background picker, fill chooser, fill popover, fill section, fill list, fills inspector, paint section]
 notes: |
   Grade is token-led, so the solid + gradient tabs lead with theme-token
   swatches (`primary`, `accent`, `secondary`, `muted`, `card`,

package/components/ui/gradient-editor.md

@@ -0,0 +1,30 @@
+---
+name: GradientEditor
+import: "@gradeui/ui"
+props:
+  - value: { type, angle?, stops } — the structured gradient (type linear/radial/angular, optional angle in deg, ordered stops). NOT a CSS string — render the string via gradientToCss(value).
+  - onChange: (value) => void — fired with the next structured gradient on any edit
+when_to_use: Edit a multi-stop CSS gradient with token-led stops. A type Select (Linear / Radial / Angular) with reverse + rotate actions, a live full-width preview bar (a Swatch type="gradient"), then a Stops list where each stop is a position %, a colour (ColorPicker token or raw), an opacity %, and a remove button; an add button appends a stop. Token stops resolve to oklch(var(--<token>)) so the preview re-voices with the theme. Emits the structured GradientValue (kept editable + serialisable); the caller turns it into CSS with the exported gradientToCss(value). Use inside a Popover from a FillSection gradient row, or standalone in a theme builder. For a single solid colour use ColorPicker; for a full paint (solid / gradient / image / shader) use FillPicker.
+composes_with: [Select, Button, Input, ColorPicker, Swatch, Popover, FillSection]
+aliases: [gradient editor, gradient picker, gradient builder, css gradient editor, stop editor, gradient stops, linear gradient editor, conic gradient editor]
+---
+
+```jsx
+<GradientEditor
+  value={{
+    type: "linear",
+    angle: 90,
+    stops: [
+      { id: "a", position: 0, token: "action/primary", opacity: 1 },
+      { id: "b", position: 100, token: "action/accent", opacity: 1 },
+    ],
+  }}
+  onChange={setGradient}
+/>
+```
+
+```jsx
+// Render the CSS string for a background.
+import { gradientToCss } from "@gradeui/ui";
+<div style={{ background: gradientToCss(gradient) }} />
+```

package/components/ui/media-surface.md

@@ -3,7 +3,7 @@ name: MediaSurface
 import: "@gradeui/ui"
 props:
   - aspect?: "video" | "square" | "portrait" | "wide" | "auto" — when omitted, derived from `hint` (album/product/food → square, portrait/poster → portrait, landscape → wide, video/audio/embed/generic → video)
-  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg") — driven by `--gds-media-radius` CSS var
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "none") — driven by `--gds-media-radius` CSS var. Square by default so a slot mounted flush at the top of a Card lets the Card clip it; set `lg`/`xl` for a standalone rounded image
   - border?: boolean (default false)
   - loading?: boolean — renders the muted skeleton overlay
   - hint?: "album" | "portrait" | "landscape" | "poster" | "product" | "food" | "video" | "audio" | "embed" | "3d" | "generic" (default "generic") — picks the placeholder glyph + the default aspect + the future generation provider

package/components/ui/section.md

@@ -0,0 +1,52 @@
+---
+name: Section
+import: "@gradeui/ui"
+subcomponents: [Container, SectionEyebrow, SectionTitle, SectionSubtitle, SectionDescription, SectionActions, SectionMedia]
+props:
+  - Section: scope? (default | inverse | brand | accent | muted | card) — colour SUBTHEME; applies the `scope-*` class so the whole band re-tones (bg/fg/card/muted/border) while action colours stay vivid. Unset = the page surface. See STUDIO-COLOR.md.
+  - Section: background?: ReactNode — visual band background slot: image / video / gradient / shader (drop a <BackgroundFill> here). Renders BEHIND the content; Section owns the relative/overflow/z plumbing. Works with `scope` (which re-tones the content tokens so text stays legible over the media).
+  - Section: pad? (none | sm | md | lg | xl) — vertical rhythm (responsive py); default lg. Section is ALWAYS full width — it never sets a max width.
+  - Section: as? (section | header | footer | div) — semantic element; default section.
+  - Container: maxW? (sm | md | lg | xl | prose | full) — centred max width + gutters; default lg. The MEASURE.
+  - Container: grid?: boolean — snap children to a 12-column grid (use `col-span-*` on children); default false.
+  - Container: as? (div | section) — semantic element; default div.
+when_to_use: THE page scaffold. A page is an ordered stack of Sections — every distinct band (hero, logos, features, pricing, testimonial, CTA, footer) gets its OWN Section so each is independently themeable. `Section` is the full-width band (scope + vertical rhythm); drop a `Container` inside it for a measure, or omit the Container for a full-bleed band. Reach for Section/Container instead of hand-rolling `<section className="py-20"><div className="max-w-7xl mx-auto px-6">`. The content inside is free — use the parts (SectionEyebrow/Title/Subtitle/Description/Actions/Media) for the common heading+copy+CTA+media shape, or drop any JSX. SectionMedia is a slot for any media (MediaSurface image, Carousel, VideoPlayer, embed, or a whole app UI). Don't use Section for app chrome — that's AppShell.
+composes_with: [Container, MediaSurface, Carousel, VideoPlayer, Button, Badge, Card, Grid, Stack]
+aliases: [section, band, hero section, page section, content section, marketing section, landing section, full bleed, container, max width wrapper, page band, section block]
+---
+
+```jsx
+// A page is a stack of Sections. Each band picks a scope; a Container
+// holds the measure (omit it to let the band bleed full-width).
+<Section scope="inverse" pad="xl">
+  <Container maxW="lg">
+    <SectionEyebrow>New</SectionEyebrow>
+    <SectionTitle>Use the agent you prefer.</SectionTitle>
+    <SectionSubtitle>Own the components. Ship on your subscription.</SectionSubtitle>
+    <SectionActions>
+      <Button size="lg">Open Studio</Button>
+      <Button size="lg" variant="outline">Docs</Button>
+    </SectionActions>
+  </Container>
+</Section>
+```
+
+```jsx
+// Full-bleed media band — no Container, so the media spans edge to edge.
+// The scope re-tones the band; the media frames itself.
+<Section scope="card" pad="lg">
+  <SectionMedia>
+    <MediaSurface hint="Studio canvas" alt="A generated screen" className="aspect-[21/9] w-full" />
+  </SectionMedia>
+</Section>
+```
+
+```jsx
+// Contained content on a grid — children snap to the 12-col Container grid.
+<Section pad="lg">
+  <Container grid>
+    <div className="col-span-12 md:col-span-7">{/* lead */}</div>
+    <div className="col-span-12 md:col-span-5">{/* aside */}</div>
+  </Container>
+</Section>
+```

package/components/ui/swatch.md

@@ -2,11 +2,14 @@
 name: Swatch
 import: "@gradeui/ui"
 subcomponents: [SwatchGroup]
-sizes: [xs, sm, md, lg, xl]
+sizes: [2xs, xs, sm, md, lg, xl]
 props:
   - color?: string — any raw CSS colour (`#1f6feb`, `oklch(...)`, `rgb(...)`, or `var(--x)`). Takes precedence over `token`. Use for one-off or external colours.
   - token?: string — a Grade colour token NAME with no `--` and no `oklch()` wrap; resolved internally to `oklch(var(--<token>))`. THE design-system path — e.g. `token="brand-3"`, `token="primary"`, `token="chart-2"`. Re-voices live when the theme changes.
-  - size? (xs | sm | md | lg | xl) — t-shirt scale, 20px → 56px; default md (32px). Prefer over h-*/w-* utilities.
+  - type? (solid | gradient | image) — fill kind; default solid (or inferred from `image` / `gradient`). Determines what the chip renders in place.
+  - gradient?: string — CSS gradient for `type="gradient"`, e.g. `linear-gradient(135deg,#6366f1,#ec4899)`.
+  - image?: string — image URL for `type="image"`; rendered cover-fit behind the chip.
+  - size? (2xs | xs | sm | md | lg | xl) — t-shirt scale, 16px → 56px; default md (32px). 2xs (16px) suits dense colour lists. Prefer over h-*/w-* utilities.
   - shape? (square | rounded | circle) — default rounded (rides `--radius`); circle for dot pickers; square for a hard tile.
   - selected?: boolean — draws the shared selection ring (`--selected`). For palette / accent pickers.
   - onSelect?: () => void — makes the swatch a pickable <button> (adds aria-pressed, focus ring, hover lift). Omit for a static display chip.

package/components/ui/toggle-group.md

@@ -2,15 +2,15 @@
 name: ToggleGroup
 import: "@gradeui/ui"
 subcomponents: [ToggleGroupItem]
-variants: [default, outline]
-sizes: [sm, md, lg]
+variants: [default, outline, segmented]
+sizes: [2xs, xs, sm, md, lg]
 props:
   - ToggleGroup: type: "single" | "multiple" — single picks one, multiple picks any number
   - ToggleGroup: value?: string | string[] — controlled; matches `type` (string for single, string[] for multiple)
   - ToggleGroup: defaultValue?: string | string[] — uncontrolled initial
   - ToggleGroup: onValueChange?: (value: string | string[]) => void
-  - ToggleGroup: size? (sm | md | lg, default md) — cascades to every ToggleGroupItem via context, matches Tabs/Button heights
-  - ToggleGroup: variant? (default | outline)
+  - ToggleGroup: size? (2xs | xs | sm | md | lg, default md) — cascades to every ToggleGroupItem via context, matches Tabs/Button heights; 2xs/xs are the dense tool-panel sizes (2xs also drops text to text-2xs and icons to size-3 so labelled items read at panel density)
+  - ToggleGroup: variant? (default | outline | segmented) — segmented sits the items in a muted track with the active item as a soft raised pill, so it reads like a TabsList; reach for it in dense property panels (e.g. a Row/Stack direction toggle)
   - ToggleGroupItem: value: string — what the group reports when this item is pressed
   - ToggleGroupItem: tooltip?: ReactNode — when set, wraps the item in a Tooltip; required for icon-only items where the visible chrome doesn't carry a label
   - ToggleGroupItem: tooltipSide? ("top" | "right" | "bottom" | "left", default "top") — side the tooltip renders on
@@ -41,3 +41,20 @@ aliases: [toggle group, segmented control, segmented buttons, button group, pill
   <ToggleGroupItem value="underline" aria-label="Underline"><Underline /></ToggleGroupItem>
 </ToggleGroup>
 ```
+
+```jsx
+// Segmented variant + 2xs — a dense property-panel toggle. Reads like a
+// tab strip (muted track, active pill) but emits a value, so it's a form
+// control, not panel-switching. This is the Studio Row/Stack control.
+<ToggleGroup
+  type="single"
+  variant="segmented"
+  size="2xs"
+  value={direction}
+  onValueChange={(v) => v && setDirection(v)}
+  className="w-full"
+>
+  <ToggleGroupItem value="row" className="flex-1"><Columns3 /> Row</ToggleGroupItem>
+  <ToggleGroupItem value="col" className="flex-1"><Rows3 /> Stack</ToggleGroupItem>
+</ToggleGroup>
+```

package/dist/composer.d.mts

@@ -0,0 +1,262 @@
+import * as React from 'react';
+import { LexicalEditor } from 'lexical';
+import { a as DemoSpeed, b as DemoTrigger } from './types-DUwnWaxR.mjs';
+
+/**
+ * Composer — the generic text composition surface for the design system.
+ *
+ * The answer wherever a user is composing a message: AI chat input,
+ * comment thread reply, post-body editor, future copilot panels.
+ * Replaces the textarea-with-buttons pattern that hosts kept rolling
+ * by hand.
+ *
+ * Built on Lexical (Meta's React-first editor framework) so it can do:
+ *   - rich text formatting (B / I / U / S / code, headings, blockquote,
+ *     pullquote, lists)
+ *   - mentions and slash commands via lexical-beautiful-mentions, with
+ *     a typeahead popover and theme-able tokens
+ *   - image attachments (paperclip + clipboard paste) when opted in
+ *   - scripted demo playback for marketing surfaces (types text, opens
+ *     mention popovers, applies formatting, all via the same step
+ *     vocabulary as <Code>)
+ *
+ * Slot-based composition for the action row: hosts that need custom
+ * affordances (template picker, voice button, attach-document) pass
+ * `leftActions` / `rightActions`. Default Send / Stop / paperclip
+ * render only when the host hasn't replaced the slot.
+ *
+ * Hosts that want the canned "chat composer with paperclip + send"
+ * preset should reach for `<AIChatComposer>` instead, which configures
+ * this Composer with the right slots wired up.
+ *
+ * Scripted demos: same `speed` / `trigger` / `play` / `loop` vocabulary
+ * as `<Code>`, sharing the underlying `useScriptedDemo` hook from
+ * `lib/demo/`. The Composer adds its own verbs (`mention`, `format`,
+ * `select`, `submit`) on top of the universal `type` / `wait` / `clear`.
+ */
+type ComposerFormat = "bold" | "italic" | "underline" | "strikethrough" | "code" | "h1" | "h2" | "h3" | "blockquote" | "pullquote" | "ul" | "ol";
+interface ComposerMentionItem {
+    id: string;
+    /** Display value (without the trigger char). */
+    value: string;
+    /** Optional secondary label shown in the suggester. */
+    label?: string;
+    /** Avatar URL or initials for the suggester row. */
+    avatar?: string;
+    /** Arbitrary payload the host can attach to the mention. */
+    data?: Record<string, unknown>;
+}
+interface ComposerTriggerConfig {
+    /** The trigger character, eg. "@" or "/". */
+    char: string;
+    /**
+     * Items to populate the suggester. Either a static array or a
+     * resolver function (sync or async) that receives the typed query.
+     * The plugin filters automatically when items is an array.
+     */
+    items: ComposerMentionItem[] | ((query: string) => ComposerMentionItem[] | Promise<ComposerMentionItem[]>);
+    /**
+     * Whether to strip the trigger char on insert. Defaults: keep for
+     * "@" (mentions read as "@alice"), strip for "/" (commands read as
+     * "Insert image" not "/insert-image").
+     */
+    stripTrigger?: boolean;
+}
+interface ComposerAttachmentConfig {
+    /** Master enable. Set true on the prop to use defaults, or pass a config object. */
+    enabled?: boolean;
+    /** HTML accept attribute on the file input. Default "image/*". */
+    accept?: string;
+    /** Max number of attachments. Default 10. */
+    maxItems?: number;
+    /** Allow multiple selection in the file picker. Default true. */
+    multiple?: boolean;
+}
+interface ComposerAttachment {
+    id: string;
+    file: File;
+    /** Object URL owned by the composer. Hosts must NOT revoke it. */
+    previewUrl: string;
+    name: string;
+}
+interface ComposerContent {
+    /** Plain text representation of the editor contents (whitespace preserved). */
+    text: string;
+    /** Lexical editor state serialised to JSON (for round-trip persistence). */
+    json: string;
+    /** Resolved mention tokens in document order. */
+    mentions: Array<{
+        trigger: string;
+        value: string;
+        data?: Record<string, unknown>;
+    }>;
+}
+interface ComposerHandle {
+    /** Run a demo script imperatively (vs. via `steps` + `trigger="manual"`). */
+    play: (steps: ComposerStep[]) => void;
+    /** Cancel an in-flight demo. Idempotent. */
+    stop: () => void;
+    /**
+     * One-shot replay of the configured `steps`. Cancels any in-flight
+     * run, clears the editor, replays from step 0. Pass a delay (ms) to
+     * schedule the replay (useful for chaining demos). Requires `steps`
+     * to be configured.
+     */
+    restart: (delayMs?: number) => void;
+    /** Move focus into the editor. */
+    focus: () => void;
+    /** Wipe the editor. */
+    clear: () => void;
+    /** Insert plain text at the current selection. */
+    insert: (text: string) => void;
+    /** Snapshot the current content + mentions. */
+    getContent: () => ComposerContent;
+    /** Direct access to the underlying Lexical editor (escape hatch). */
+    getEditor: () => LexicalEditor | null;
+}
+/**
+ * Demo step vocabulary for Composer scripts. Shares `type` / `wait` /
+ * `clear` with the universal `lib/demo` verbs; adds composer-specific
+ * `mention`, `format`, `select`, `newline`, `submit` on top.
+ */
+type ComposerStep = {
+    type: "type";
+    text: string;
+    speed?: DemoSpeed;
+} | {
+    type: "wait";
+    ms: number;
+} | {
+    type: "clear";
+} | {
+    type: "newline";
+} | {
+    type: "submit";
+} | {
+    type: "mention";
+    /** Trigger char (must match a registered ComposerTriggerConfig.char). */
+    trigger: string;
+    /** Value to insert (without the trigger). Looks up the matching item by `value`. */
+    value: string;
+    /** Optional pre-typed query — the demo types this after the trigger char before "selecting" the value, to show the typeahead in action. */
+    query?: string;
+} | {
+    type: "format";
+    format: ComposerFormat;
+} | {
+    type: "select";
+    /** Substring to find and select. First match wins. */
+    text: string;
+};
+interface ComposerProps {
+    /** Placeholder copy shown when empty. */
+    placeholder?: string;
+    /** Initial plain text content. For richer initial state, use `initialJson`. */
+    initialText?: string;
+    /** Initial Lexical state JSON (from a previous `onSubmit` round-trip). */
+    initialJson?: string;
+    /**
+     * Available formats. Pass false to disable rich text entirely
+     * (plain text mode, half the bundle weight, no toolbar). Default
+     * enables a sensible set for most chat / comment surfaces.
+     */
+    formats?: ComposerFormat[] | false;
+    /**
+     * Render the formatting toolbar. Default false because most uses
+     * are short-form. Set true (or "top") to show the toolbar above the
+     * editor. "floating" is planned; not yet implemented.
+     */
+    toolbar?: boolean | "top";
+    /**
+     * Mention / slash command configs. Each entry registers one trigger
+     * char and its items. Pass `[{ char: "@", items: people }, { char: "/", items: commands }]`
+     * for the common chat-app setup.
+     */
+    triggers?: ComposerTriggerConfig[];
+    /**
+     * Image attachments (paperclip + clipboard paste). Pass true for
+     * defaults, an object to customise, or omit/false to skip the
+     * attachment plumbing entirely.
+     */
+    attachments?: boolean | ComposerAttachmentConfig;
+    /** Fires when the user submits (Enter, click Send, or scripted `submit` step). */
+    onSubmit?: (content: ComposerContent, attachments?: ComposerAttachment[]) => void;
+    /**
+     * Fires on every editor change with the current plain text. Use for
+     * length validation, controlled-value bridges (eg. AIChatComposer
+     * forwarding to a host's `value`/`onChange` pair), or live preview
+     * surfaces. Cheap, called frequently; debounce if you need the
+     * Lexical state JSON (use `getContent()` via ref instead).
+     */
+    onChange?: (text: string) => void;
+    /**
+     * Loading state — disables the editor + paperclip and swaps the
+     * default Send button for Stop. Has no effect when `rightActions`
+     * overrides the default Send.
+     */
+    isLoading?: boolean;
+    /** Stop handler — required for Stop to be active when loading. */
+    onStop?: () => void;
+    /** Hard character cap. */
+    maxLength?: number;
+    /** Auto-focus the editor on mount. Default false. */
+    autoFocus?: boolean;
+    /** Whether Enter submits. Default true (Shift-Enter still inserts a newline). */
+    submitOnEnter?: boolean;
+    /**
+     * Custom content for the left action slot. Replaces the default
+     * paperclip button when `attachments` is enabled.
+     */
+    leftActions?: React.ReactNode;
+    /**
+     * Custom content for the right action slot. Replaces the default
+     * Send / Stop button. Use the `useComposer()` hook inside to access
+     * imperative methods.
+     */
+    rightActions?: React.ReactNode;
+    /** Hide the default Send button without replacing it. */
+    hideSend?: boolean;
+    /** Scripted demo steps. */
+    steps?: ComposerStep[];
+    /** What kicks the script off. Defaults to "mount". */
+    trigger?: DemoTrigger;
+    /** For trigger="manual" — flip true to play. */
+    play?: boolean;
+    /** Animation feel. */
+    speed?: DemoSpeed;
+    /** Loop the script forever. */
+    loop?: boolean;
+    /**
+     * Pause between loop iterations (ms). Defaults to 2000. Marketing
+     * heroes that want the demo to breathe between repeats bump this
+     * higher; tight inline demos drop it.
+     */
+    loopDelay?: number;
+    /**
+     * Fires once per loop cycle, AFTER the loopDelay pause and BEFORE
+     * the script replays. Use to reset parent state that the script
+     * mutated via onSubmit (e.g., wipe a messages list back to its
+     * seed before the demo types into it again). The editor is cleared
+     * automatically — you only need this hook if state outside the
+     * Composer needs to reset too.
+     */
+    onLoopReset?: () => void;
+    /**
+     * Bare mode — strip the card chrome (border / bg / rounding). Use
+     * when embedding inside an existing card or column layout.
+     */
+    bare?: boolean;
+    /**
+     * Read-only mode — disables editing AND focusability. Programmatic
+     * updates (including scripted demo playback) still work. Use for
+     * marketing surfaces that render a Composer purely for show, so the
+     * scripted typing doesn't steal focus from other inputs on the page.
+     * Hides the default Send / paperclip action row.
+     */
+    readOnly?: boolean;
+    className?: string;
+}
+declare const Composer: React.ForwardRefExoticComponent<ComposerProps & React.RefAttributes<ComposerHandle>>;
+declare const ComposerReply: React.ForwardRefExoticComponent<ComposerProps & React.RefAttributes<ComposerHandle>>;
+
+export { Composer, type ComposerAttachment, type ComposerAttachmentConfig, type ComposerContent, type ComposerFormat, type ComposerHandle, type ComposerMentionItem, type ComposerProps, ComposerReply, type ComposerStep, type ComposerTriggerConfig };