@create-ui/cli 0.5.8 → 0.6.0

package/dist/skills/createui/reference/field.md

@@ -0,0 +1,186 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/field.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/field.md -->
+
+# field
+
+Form field wrapper that owns the xs/sm/md size cascade; Input, Select and Textarea inherit size and state via context
+
+Install: `npx @create-ui/cli add field`
+
+## Import
+
+```tsx
+import { Field, FieldLabel, FieldTitle, FieldContent, FieldDescription, FieldError, FieldFooter, FieldGroup, FieldHelper, FieldLegend, FieldSeparator, FieldSet } from "@/components/ui/field"
+```
+
+Also exported: `LabelDescription`, `fieldVariants`, `fieldLabelVariants`, `fieldTitleVariants`, `fieldDescriptionVariants`, `fieldHelperVariants`, `fieldErrorVariants`, `fieldFooterVariants`, `fieldLegendVariants`, `useFieldContext`, `useOptionalFieldContext`
+
+## Field props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (cascades via context to Input/Select/Textarea/labels; set it ONCE here) | `sm` |
+| orientation | `vertical \| horizontal \| responsive` (horizontal puts the label beside the control (settings rows); responsive only inlines inside a FieldGroup) | `vertical` |
+| invalid | `boolean` | - |
+| disabled | `boolean` | - |
+| loading | `boolean` | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## FieldTitle props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (cascades via context to Input/Select/Textarea/labels; set it ONCE here) | `sm` |
+
+Extends `React.ComponentProps<"div">`.
+
+## FieldDescription props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (cascades via context to Input/Select/Textarea/labels; set it ONCE here) | `sm` |
+
+Extends `React.ComponentProps<"p">`.
+
+## FieldError props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (cascades via context to Input/Select/Textarea/labels; set it ONCE here) | `sm` |
+| errors | `Array<{ message?: string } \| undefined>` (deduped by message; bulleted list when >1; renders nothing when empty) | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## FieldFooter props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (cascades via context to Input/Select/Textarea/labels; set it ONCE here) | `sm` |
+
+Extends `React.ComponentProps<"div">`.
+
+## FieldHelper props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md` (cascades via context to Input/Select/Textarea/labels; set it ONCE here) | `sm` |
+| tone | `neutral \| error` (auto-defaults to error when the Field is invalid) | `neutral` |
+| icon | `ReactNode` (the only Field part that takes its icon as a prop, not a child slot) | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## FieldLegend props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `legend \| label` (label downsizes the legend to match a default (sm) FieldLabel; FieldLegend ignores Field size context) | `legend` |
+
+Extends `React.ComponentProps<"legend">`.
+
+## FieldSeparator props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| children | `ReactNode` | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## Examples
+
+From `field-demo`:
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+
+export default function FieldDemo() {
+  return (
+    <Field className="w-full max-w-sm">
+      <FieldLabel htmlFor="field-demo-email">Email Address</FieldLabel>
+      <Input id="field-demo-email" type="email" placeholder="you@example.com" />
+      <FieldDescription>
+        We&apos;ll never share your email with anyone.
+      </FieldDescription>
+    </Field>
+  )
+}
+```
+
+From `field-composition`:
+
+```tsx
+import {
+  Field,
+  FieldContent,
+  FieldDescription,
+  FieldGroup,
+  FieldLabel,
+} from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+import { Switch } from "@/components/ui/switch"
+import { Textarea } from "@/components/ui/textarea"
+
+export default function FieldComposition() {
+  return (
+    <FieldGroup className="w-full max-w-sm">
+      <Field size="md">
+        <FieldLabel htmlFor="field-compose-name">Full Name</FieldLabel>
+        <Input id="field-compose-name" placeholder="Jane Doe" />
+      </Field>
+      <Field size="md">
+        <FieldLabel htmlFor="field-compose-country">Country</FieldLabel>
+        <Select>
+          <SelectTrigger id="field-compose-country">
+            <SelectValue placeholder="Select your country" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectGroup>
+              <SelectItem value="us">United States</SelectItem>
+              <SelectItem value="uk">United Kingdom</SelectItem>
+              <SelectItem value="ca">Canada</SelectItem>
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+      </Field>
+      <Field size="md">
+        <FieldLabel htmlFor="field-compose-bio">Bio</FieldLabel>
+        <Textarea id="field-compose-bio" placeholder="A few sentences" />
+      </Field>
+      <Field size="md" orientation="horizontal">
+        <FieldContent>
+          <FieldLabel htmlFor="field-compose-marketing">
+            Marketing Emails
+          </FieldLabel>
+          <FieldDescription>
+            Receive product news and occasional offers.
+          </FieldDescription>
+        </FieldContent>
+        <Switch id="field-compose-marketing" />
+      </Field>
+    </FieldGroup>
+  )
+}
+```
+
+More: `npx @create-ui/cli view field` or MCP `get_item_examples_from_registries` with "field-demo" / "field-example".
+
+## When to use
+
+Layout and context wrapper for every labeled form control: forms are `FieldGroup` > `Field`(s), never raw divs with `space-y-*`. The control inside is `Input`/`Select`/`Textarea`/`Checkbox`/`Switch`; a multi-option group that is one logical control should be `RadioGroup` or `CheckboxGroup` instead. Group related fields with `FieldSet` + `FieldLegend`, not a heading div.
+
+## Gotchas
+
+- Set `size`/`invalid`/`disabled`/`loading` once on `Field`; nested controls and `Field*` parts resolve explicit prop ?? context ?? default - never re-set them on children. `Field` also derives state from `data-invalid`/`data-disabled`/`data-loading` attributes when the boolean props are absent.
+- `orientation="responsive"` switches via a container query that only `FieldGroup` provides (`@container/field-group`); a responsive `Field` without a `FieldGroup` ancestor stays stacked forever.
+- Horizontal checkbox/switch rows: stack `FieldLabel` + `FieldDescription` inside `FieldContent` as a DIRECT child of `Field` - the alignment switch keys off `has-[>[data-slot=field-content]]`. Rich choice cards use `Label` + `LabelDescription` inside `LabelMain` there, not `FieldLabel` + `FieldDescription`.
+- Render `FieldError` unconditionally; it returns null when it has no `children` and no `errors`, and `children` take precedence over `errors`. It ships with `role="alert"`.
+- `FieldTitle` renders a `<div>` with no `htmlFor` association, but it shares `data-slot="field-label"`, so horizontal layout treats it like a label; use it for non-labelable controls such as a segmented control.
+- Vertical (default) Field forces every direct child to full width via [&>*]:w-full; self-start does NOT stop the stretch. For intrinsic-width controls (SegmentedControl, a lone Button), use orientation="horizontal" or wrap the control in a plain div.

package/dist/skills/createui/reference/info-tooltip.md

@@ -0,0 +1,110 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/info-tooltip.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/info-tooltip.md -->
+
+# info-tooltip
+
+Tooltip with a built-in info icon trigger for field hints; pass variant/size on the root for the simplified API
+
+Install: `npx @create-ui/cli add info-tooltip`
+
+## Import
+
+```tsx
+import { InfoTooltip, InfoTooltipContent, InfoTooltipProvider, InfoTooltipTrigger } from "@/components/ui/info-tooltip"
+```
+
+Also exported: `infoTooltipContentVariants`
+
+## InfoTooltip props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| inverse \| danger \| info` | - |
+| size | `sm \| md \| lg` | - |
+| side | `top \| bottom \| left \| right` | - |
+| align | `start \| center \| end` | - |
+| showArrow | `boolean` (When false, sideOffset is auto-increased by 7 so the gap matches the arrow version) | - |
+| className | `string` | - |
+
+Extends `React.ComponentProps< typeof TooltipPrimitive.Root >`.
+
+## InfoTooltipContent props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| inverse \| danger \| info` | `primary` |
+| size | `sm \| md \| lg` | `sm` |
+| children | `ReactNode` | - |
+| className | `string` | - |
+| showArrow | `boolean` (When false, sideOffset is auto-increased by 7 so the gap matches the arrow version) | `true` |
+| side | `top \| bottom \| left \| right` | `bottom` |
+| align | `start \| center \| end` | `center` |
+| sideOffset | `number` | `2.5` |
+| alignOffset | `number` (Auto-resolves for align start/end to -12 (sm/md) or -16 (lg); center gets 0) | - |
+
+Extends `React.ComponentProps<typeof TooltipPrimitive.Content>`.
+
+## InfoTooltipTrigger props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| children | `ReactNode` | - |
+| asChild | `boolean` | - |
+| variant | `primary \| neutral \| inverse \| danger \| info` | - |
+| size | `sm \| md \| lg` | - |
+| className | `string` | - |
+
+Extends `React.ComponentProps<typeof TooltipPrimitive.Trigger>`.
+
+## Examples
+
+From `label-info-tooltip`:
+
+```tsx
+import { RiKey2Line } from "@create-ui/assets/icons"
+
+import { Field } from "@/components/ui/field"
+import { InfoTooltip } from "@/components/ui/info-tooltip"
+import { Input } from "@/components/ui/input"
+import { Label, LabelIcon, LabelInfoSlot } from "@/components/ui/label"
+
+export default function LabelInfoTooltip() {
+  return (
+    <Field className="w-full max-w-xs">
+      <Label htmlFor="label-info">
+        <LabelIcon>
+          <RiKey2Line />
+        </LabelIcon>
+        API token
+        <LabelInfoSlot>
+          <InfoTooltip variant="inverse" size="sm" side="top">
+            Used to authenticate API requests. Keep it secret, treat it like a
+            password, and rotate it right away if it ever leaks or shows up in a
+            commit.
+          </InfoTooltip>
+        </LabelInfoSlot>
+      </Label>
+      <Input id="label-info" placeholder="sk-…" />
+    </Field>
+  )
+}
+```
+
+More: `npx @create-ui/cli view info-tooltip` or MCP `get_item_examples_from_registries` with "info-tooltip-demo" / "info-tooltip-example".
+
+## When to use
+A "what is this?" helper with a built-in info-circle icon trigger, typically next to a field label (canonical placement: inside `LabelInfoSlot` within `Label`, see label-info-tooltip). Do NOT use it for hover hints on arbitrary elements like buttons; that is `Tooltip`. There is no popover component for click-to-open rich content - surface that content inline.
+
+## Gotchas
+- The root has two modes. Setting `variant` OR `size` on `InfoTooltip` activates the simplified API: children become the tooltip TEXT and the icon trigger plus content are auto-rendered. With neither prop set it is a bare Radix Root: compose `InfoTooltipTrigger` + `InfoTooltipContent` yourself, and `side`/`align`/`showArrow`/`className` on the root do nothing.
+- In composed mode there is no context cascade: pass the same `variant`/`size` to BOTH `InfoTooltipTrigger` (icon color/size) and `InfoTooltipContent` (bubble styling). The arrow fill is derived by Content from its own `variant`.
+- `InfoTooltipTrigger` with no children renders a built-in inline info SVG; passing children replaces it entirely and the trigger's `variant`/`size` stop doing anything. The trigger always carries the `group` class, so custom children can style via `group-hover:` and `group-data-[state=open]:`.
+- Placement defaults to bottom (shadcn/Radix tooltips default to top). An AI trained on shadcn will also reach for `TooltipProvider` + `Trigger asChild` + `Content`; the intended common form is the one-liner:
+
+```tsx
+<InfoTooltip variant="inverse" size="sm" side="top">
+  Helper text
+</InfoTooltip>
+```
+
+- It does not read Field context; set `size` explicitly even inside a `Field`/`Label`.
+- The icon is hardcoded inline in the component, not imported from `@create-ui/assets/icons`; do not "fix" it to a Remix icon.

package/dist/skills/createui/reference/inline-alert.md

@@ -0,0 +1,146 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/inline-alert.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/inline-alert.md -->
+
+# inline-alert
+
+Dismissible callout for in-page messages; seven variants by four appearances with horizontal or vertical layout
+
+Install: `npx @create-ui/cli add inline-alert`
+
+## Import
+
+```tsx
+import { InlineAlert, InlineAlertIcon, InlineAlertContent, InlineAlertHeading, InlineAlertTitle, InlineAlertDescription, InlineAlertActions, InlineAlertClose } from "@/components/ui/inline-alert"
+```
+
+Also exported: `inlineAlertVariants`, `useInlineAlertContext`
+
+## InlineAlert props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| danger \| success \| warning \| info \| away` | `primary` |
+| appearance | `solid \| soft \| outline \| default` (default = neutral card (border + shadow; variant tints only the icon); soft = tinted fill; solid = filled high-emphasis; outline = tinted text + colored border) | `default` |
+| layout | `horizontal \| vertical` (horizontal nowraps the title and clamps description to 2 lines; vertical clamps at 5 - use vertical for longer copy) | `horizontal` |
+| onDismiss | `() => void` (fires when the 300ms exit transition ends, not on close click) | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## Examples
+
+From `inline-alert-demo`:
+
+```tsx
+import { RiInformationFill } from "@create-ui/assets/icons"
+
+import {
+  InlineAlert,
+  InlineAlertContent,
+  InlineAlertDescription,
+  InlineAlertHeading,
+  InlineAlertIcon,
+  InlineAlertTitle,
+} from "@/components/ui/inline-alert"
+
+export default function InlineAlertDemo() {
+  return (
+    <InlineAlert>
+      <InlineAlertIcon>
+        <RiInformationFill />
+      </InlineAlertIcon>
+      <InlineAlertContent>
+        <InlineAlertHeading>
+          <InlineAlertTitle>Heads up</InlineAlertTitle>
+          <InlineAlertDescription>
+            Your changes have been saved to the draft.
+          </InlineAlertDescription>
+        </InlineAlertHeading>
+      </InlineAlertContent>
+    </InlineAlert>
+  )
+}
+```
+
+From `inline-alert-dismissible`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { RiCheckboxCircleFill } from "@create-ui/assets/icons"
+
+import { Button } from "@/components/ui/button"
+import {
+  InlineAlert,
+  InlineAlertClose,
+  InlineAlertContent,
+  InlineAlertDescription,
+  InlineAlertHeading,
+  InlineAlertIcon,
+  InlineAlertTitle,
+} from "@/components/ui/inline-alert"
+
+export default function InlineAlertDismissible() {
+  const [visible, setVisible] = React.useState(true)
+
+  if (!visible) {
+    return (
+      <Button
+        variant="neutral-light"
+        appearance="outline"
+        size="md"
+        onClick={() => setVisible(true)}
+      >
+        Show alert again
+      </Button>
+    )
+  }
+
+  return (
+    <InlineAlert variant="success" onDismiss={() => setVisible(false)}>
+      <InlineAlertIcon>
+        <RiCheckboxCircleFill />
+      </InlineAlertIcon>
+      <InlineAlertContent>
+        <InlineAlertHeading>
+          <InlineAlertTitle>Saved</InlineAlertTitle>
+          <InlineAlertDescription>
+            Your settings are up to date. Dismiss this banner to remove it from
+            the page.
+          </InlineAlertDescription>
+        </InlineAlertHeading>
+      </InlineAlertContent>
+      <InlineAlertClose />
+    </InlineAlert>
+  )
+}
+```
+
+More: `npx @create-ui/cli view inline-alert` or MCP `get_item_examples_from_registries` with "inline-alert-demo" / "inline-alert-example".
+
+## When to use
+
+In-flow status callouts anchored to content: form-level validation summaries, plan notices, saved confirmations. There is no page-banner component; build a top-of-page announcement from semantic-token markup rather than stretching an InlineAlert. Ephemeral screen-level feedback is `Toast`; per-field validation is `Field` error/helper text.
+
+## Gotchas
+
+- Nesting is strict and deeper than shadcn's flat Alert: `InlineAlertTitle` + `InlineAlertDescription` go inside `InlineAlertHeading`, which sits next to `InlineAlertActions` inside `InlineAlertContent`. In horizontal layout Content is a flex row, so an unwrapped Title/Description render side by side instead of stacked.
+
+```tsx
+<InlineAlert variant="warning" appearance="soft" onDismiss={removeFromState}>
+  <InlineAlertIcon><RiErrorWarningFill /></InlineAlertIcon>
+  <InlineAlertContent>
+    <InlineAlertHeading>
+      <InlineAlertTitle>Storage almost full</InlineAlertTitle>
+      <InlineAlertDescription>Upgrade to keep receiving uploads.</InlineAlertDescription>
+    </InlineAlertHeading>
+    <InlineAlertActions>{/* Button / TextLink */}</InlineAlertActions>
+  </InlineAlertContent>
+  <InlineAlertClose />
+</InlineAlert>
+```
+
+- `InlineAlertClose` always renders absolutely at the alert's top-right corner (the root is its only positioned ancestor), and the root auto-reserves clearance for it (`pr-12` horizontal, title right-padding vertical). Keep it a direct child of the root; nesting it inside `InlineAlertActions` does not put it in flow, it still jumps to the corner.
+- Dismissal is self-contained: Close triggers a fade/scale exit, then the component unmounts itself (returns null). Sync external state in `onDismiss`, not in your own Close `onClick`, or the exit transition is cut off.
+- `InlineAlertClose` auto-adapts its CloseButton to context (inverse on solid appearance, neutral otherwise); leave its variant unset.
+- `InlineAlertIcon` sizes (`[&_svg]:size-5`) and colors the glyph from variant/appearance context; pass a bare `Ri*` icon with no size or color classes.
+- Unlike shadcn's Alert, the default variant is `primary`, so an unconfigured alert's icon reads brand-tinted, not gray; use `variant="neutral"` for a plain note.

package/dist/skills/createui/reference/input-group.md

@@ -0,0 +1,171 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/input-group.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/input-group.md -->
+
+# input-group
+
+Composable input shell with slots for icons, addons, selects, buttons, kbd hints and card badges around the control
+
+Install: `npx @create-ui/cli add input-group`
+
+## Import
+
+```tsx
+import { InputGroup, InputGroupProvider, InputGroupShell, InputGroupSlot, InputGroupControl, InputGroupTextarea, InputGroupToolbar, InputGroupLeadingIcon, InputGroupAddon, InputGroupSelect, InputGroupButton, InputGroupCard, InputGroupKbd, InputGroupHelperIcon, InputGroupField } from "@/components/ui/input-group"
+```
+
+Also exported: `useInputGroup`, `useOptionalInputGroup`
+
+## InputGroup props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `InputSize` (xs | sm | md (the InputSize scale); usually inherited from Field - set it once there) | - |
+| invalid | `boolean` | - |
+| disabled | `boolean` | - |
+| loading | `boolean` | - |
+| multiline | `boolean` (switches the shell to flex-col; pair with InputGroupTextarea instead of InputGroupControl) | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## InputGroupProvider props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `InputSize` (xs | sm | md (the InputSize scale); usually inherited from Field - set it once there) | `sm` |
+| invalid | `boolean` | - |
+| disabled | `boolean` | `false` |
+| loading | `boolean` | `false` |
+| children | `ReactNode` | - |
+
+## InputGroupToolbar props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| position | `start \| end \| between` | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## InputGroupSelect props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| className | `string` | - |
+| triggerClassName | `string` | - |
+| placeholder | `ReactNode` | - |
+| prefix | `ReactNode` | - |
+| valueChildren | `ReactNode` | - |
+| aria-label | `string` | - |
+| aria-labelledby | `string` | - |
+
+Extends `React.ComponentProps<typeof Select>`.
+
+## InputGroupHelperIcon props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| invalidIcon | `ReactNode` | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## InputGroupField props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| label | `ReactNode` | - |
+| description | `ReactNode` | - |
+| error | `ReactNode` | - |
+| size | `InputSize` (xs | sm | md (the InputSize scale); usually inherited from Field - set it once there) | `sm` |
+| disabled | `boolean` | - |
+| children | `ReactNode` | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## Examples
+
+From `input-group-demo`:
+
+```tsx
+import { RiSearch2Line } from "@create-ui/assets/icons"
+
+import {
+  InputGroup,
+  InputGroupButton,
+  InputGroupControl,
+  InputGroupKbd,
+  InputGroupSlot,
+} from "@/components/ui/input-group"
+
+export default function InputGroupDemo() {
+  return (
+    <InputGroup className="max-w-md">
+      <InputGroupSlot>
+        <RiSearch2Line />
+        <InputGroupControl placeholder="Search anything…" />
+        <InputGroupKbd>K</InputGroupKbd>
+      </InputGroupSlot>
+      <InputGroupButton>Search</InputGroupButton>
+    </InputGroup>
+  )
+}
+```
+
+From `input-group-with-select`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import { Field, FieldLabel } from "@/components/ui/field"
+import {
+  InputGroup,
+  InputGroupControl,
+  InputGroupLeadingIcon,
+  InputGroupSelect,
+  InputGroupSlot,
+} from "@/components/ui/input-group"
+import { SelectItem } from "@/components/ui/select"
+
+const CURRENCY_SYMBOLS: Record<string, string> = {
+  usd: "$",
+  eur: "€",
+  gbp: "£",
+}
+
+export default function InputGroupWithSelect() {
+  const [currency, setCurrency] = React.useState("usd")
+
+  return (
+    <Field className="max-w-md">
+      <FieldLabel htmlFor="input-group-with-select-amount">Amount</FieldLabel>
+      <InputGroup>
+        <InputGroupLeadingIcon>
+          <span className="font-medium">{CURRENCY_SYMBOLS[currency]}</span>
+        </InputGroupLeadingIcon>
+        <InputGroupSlot>
+          <InputGroupControl
+            id="input-group-with-select-amount"
+            placeholder="0.00"
+          />
+        </InputGroupSlot>
+        <InputGroupSelect value={currency} onValueChange={setCurrency}>
+          <SelectItem value="usd">USD</SelectItem>
+          <SelectItem value="eur">EUR</SelectItem>
+          <SelectItem value="gbp">GBP</SelectItem>
+        </InputGroupSelect>
+      </InputGroup>
+    </Field>
+  )
+}
+```
+
+More: `npx @create-ui/cli view input-group` or MCP `get_item_examples_from_registries` with "input-group-demo" / "input-group-example".
+
+## When to use
+InputGroup is the shell for a single value that needs visible chrome: search bars with kbd hints and a submit button, URL fields with an https:// addon, amounts with a trailing currency select, passwords with a built-in show/hide toggle. For plain capture with no affordances use Input (or Textarea for multiline); for one-character-per-slot codes use InputOTP; for increment/decrement use InputStepper.
+## Gotchas
+- Never put a raw Input or Textarea inside the group; use InputGroupControl (single-line) or InputGroupTextarea (multiline). InputGroupControl strips its own height/padding (h-auto p-0) and relies on InputGroupSlot for size and state styling.
+- Two layers of placement: inline adornments (plain svg icons, InputGroupKbd, InputGroupHelperIcon) go INSIDE InputGroupSlot next to the control; bordered chrome (InputGroupLeadingIcon, InputGroupAddon, InputGroupSelect, InputGroupButton) goes as direct children of the group. The shell auto-draws 1px dividers between direct children.
+- size/invalid/disabled/loading cascade Field -> InputGroup -> every sub-part; set them once on Field. InputGroupSelect goes variant="compact" and InputGroupButton maps the group size to its own scale (xs->md, sm->lg, md->xl) automatically; do not re-set variant/size on them.
+- States do more than recolor: invalid auto-disables InputGroupButton; loading disables InputGroupButton and InputGroupSelect, appends a Spinner inside the slot, and makes InputGroupTextarea readOnly.
+- InputGroupControl type="password" auto-renders a show/hide eye toggle (with aria-pressed); it hides while loading and disables with the group. No extra wiring.
+- InputGroupKbd shows a command-key leading icon by default; pass leadingIcon={null} for plain single-key hints.