@create-ui/cli 0.5.8 → 0.6.0

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

@@ -0,0 +1,162 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/toast.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/toast.md -->
+
+# toast
+
+Notification card with icon, action and close slots plus ToastProgress countdown; seven variants by four appearances
+
+Install: `npx @create-ui/cli add toast`
+
+## Import
+
+```tsx
+import { Toast, ToastBody, ToastIcon, ToastContent, ToastTitle, ToastDescription, ToastAction, ToastClose, ToastProgress } from "@/components/ui/toast"
+```
+
+Also exported: `toastVariants`, `useToastContext`
+
+## Toast props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| danger \| success \| warning \| info \| away` | `primary` |
+| appearance | `solid \| soft \| outline \| default` (solid = filled, soft/outline/default = quieter surfaces) | `solid` |
+
+Extends `React.ComponentProps<"div">`.
+
+## ToastProgress props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| value | `number` | - |
+| duration | `number` (CSS tween duration per value change (default 150ms); for a lifetime countdown set it to the toast's full lifetime in ms) | `150` |
+
+Extends `React.ComponentProps<"div">`.
+
+## Examples
+
+From `toast-demo`:
+
+```tsx
+import { RiInformationFill } from "@create-ui/assets/icons"
+
+import {
+  Toast,
+  ToastBody,
+  ToastContent,
+  ToastDescription,
+  ToastIcon,
+  ToastTitle,
+} from "@/components/ui/toast"
+
+export default function ToastDemo() {
+  return (
+    <Toast>
+      <ToastBody>
+        <ToastIcon>
+          <RiInformationFill />
+        </ToastIcon>
+        <ToastContent>
+          <ToastTitle>New update available</ToastTitle>
+          <ToastDescription>Version 2.1 is ready to install.</ToastDescription>
+        </ToastContent>
+      </ToastBody>
+    </Toast>
+  )
+}
+```
+
+From `toast-with-progress`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { RiInformationFill } from "@create-ui/assets/icons"
+
+import { Button } from "@/components/ui/button"
+import {
+  Toast,
+  ToastBody,
+  ToastContent,
+  ToastDescription,
+  ToastIcon,
+  ToastProgress,
+  ToastTitle,
+} from "@/components/ui/toast"
+
+const DURATION_MS = 5000
+
+export default function ToastWithProgress() {
+  const [visible, setVisible] = React.useState(true)
+  const [progress, setProgress] = React.useState(0)
+
+  React.useEffect(() => {
+    if (!visible) return
+
+    const raf = requestAnimationFrame(() => setProgress(100))
+    const timeout = setTimeout(() => setVisible(false), DURATION_MS)
+
+    return () => {
+      cancelAnimationFrame(raf)
+      clearTimeout(timeout)
+    }
+  }, [visible])
+
+  if (!visible) {
+    return (
+      <Button
+        variant="neutral-light"
+        appearance="outline"
+        onClick={() => {
+          setProgress(0)
+          setVisible(true)
+        }}
+      >
+        Show toast again
+      </Button>
+    )
+  }
+
+  return (
+    <Toast variant="info" appearance="soft">
+      <ToastBody>
+        <ToastIcon>
+          <RiInformationFill />
+        </ToastIcon>
+        <ToastContent>
+          <ToastTitle>Auto-dismissing in 5s</ToastTitle>
+          <ToastDescription>
+            The progress bar tracks the remaining lifetime of this toast.
+          </ToastDescription>
+        </ToastContent>
+      </ToastBody>
+      <ToastProgress value={progress} duration={DURATION_MS} />
+    </Toast>
+  )
+}
+```
+
+More: `npx @create-ui/cli view toast` or MCP `get_item_examples_from_registries` with "toast-demo" / "toast-example".
+
+## When to use
+
+Ephemeral, floating confirmation of an action ("Draft saved", "Copied"); render it in a screen-level fixed container. Not for status that belongs to a section (use `InlineAlert`), blocking confirm/cancel decisions (use `Dialog`), or per-field validation (use `Field` helper/error text).
+
+## Gotchas
+
+- There is no `toast()` function, no `Toaster`, no app-level provider, no portal, no queue or positioning system. `Toast` is just the card; render active toasts from your own state into a fixed container. Do NOT install or import `sonner`.
+- Dismiss lifecycle: `ToastClose` starts a 300ms fade/scale exit; the root's `onDismiss` fires only after the transition ends, then the component renders `null`. Remove the toast from your list in `onDismiss`, not in `ToastClose`'s `onClick`. Once dismissed it stays hidden; re-showing requires a remount (state toggle or new `key`).
+- `ToastProgress` never ticks by itself and is `aria-hidden` (purely visual). For an auto-dismissing toast, set `duration` to the lifetime, flip `value` from 0 to 100 inside `requestAnimationFrame`, and pair it with a `setTimeout` that actually hides the toast:
+
+```tsx
+React.useEffect(() => {
+  const raf = requestAnimationFrame(() => setProgress(100))
+  const timeout = setTimeout(() => setVisible(false), DURATION_MS)
+  return () => { cancelAnimationFrame(raf); clearTimeout(timeout) }
+}, [])
+// <ToastProgress value={progress} duration={DURATION_MS} />
+```
+
+- `ToastIcon`, `ToastDescription`, `ToastAction`, `ToastClose`, and `ToastProgress` read the Toast context, so they only style correctly inside `<Toast>`. Don't hand-set Button variants on `ToastAction`/`ToastClose` (the appearance-matched pairing is automatic) or color/size classes on the icon (the svg is auto-sized `size-5` and colored per variant/appearance).
+- The root is hard-coded `w-[410px] min-w-[300px]`; override the width via `className` for narrow viewports.
+- The root renders `role="status"` (polite live region); pass `role="alert"` for urgent messages. No Escape-key handling is wired; dismissal happens only through `ToastClose` (or `useToastContext().dismiss`).

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

@@ -0,0 +1,63 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/tooltip.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/tooltip.md -->
+
+# tooltip
+
+Radix hover tooltip for any trigger element; five color variants, optional arrow, side and offset control
+
+Install: `npx @create-ui/cli add tooltip`
+
+## Import
+
+```tsx
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip"
+```
+
+Also exported: `tooltipContentVariants`
+
+## TooltipContent props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| children | `ReactNode` | - |
+| className | `string` | - |
+| variant | `primary \| neutral \| inverse \| danger \| info` | `primary` |
+| showArrow | `boolean` (effective offset = sideOffset when true; sideOffset + 5 when false, so the chip keeps a visible gap without the caret) | `false` |
+| side | `top \| bottom \| left \| right` (defaults to bottom; shadcn/Radix default to top, do not assume top) | `bottom` |
+| sideOffset | `number` | `2.5` |
+
+Extends `React.ComponentProps<typeof TooltipPrimitive.Content>`.
+
+## Examples
+
+From `tooltip-demo`:
+
+```tsx
+"use client"
+
+import { Button } from "@/components/ui/button"
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
+
+export default function TooltipDemo() {
+  return (
+    <Tooltip defaultOpen>
+      <TooltipTrigger asChild>
+        <Button appearance="outline" size="sm">
+          Hover me
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent showArrow>Add to library</TooltipContent>
+    </Tooltip>
+  )
+}
+```
+
+More: `npx @create-ui/cli view tooltip` or MCP `get_item_examples_from_registries` with "tooltip-demo" / "tooltip-example".
+
+## When to use
+Tooltip is a short hover/focus hint for icon-only buttons, truncated labels, and similar read-only context. Content must stay brief: the chip caps at max-w-[200px] and wraps. For content with links, buttons, or inputs there is no popover component - put it inline; for a help icon next to a label use InfoTooltip; for post-action messages use Toast; for a persistent in-flow note use InlineAlert.
+## Gotchas
+- Tooltip self-provides its Radix Provider and passes delayDuration (default 0) explicitly to both Provider and Root, so an ancestor TooltipProvider's delayDuration never reaches it. Set delay per instance: `<Tooltip delayDuration={400}>`. The exported TooltipProvider only matters for raw TooltipPrimitive.Root subtrees.
+- align is hardcoded to "center" and Omit-ed from the passthrough type; it cannot be overridden.
+- TooltipTrigger should use asChild wrapping a focusable registry element (Button, link); the trigger always gets an `inline-flex` class so the wrapped child lays out consistently.
+- TooltipArrow is internal and not exported; the only way to render the caret is `showArrow` on TooltipContent, and its fill auto-matches the chosen variant. Never try to style or compose the arrow separately.
+- InfoTooltip is a separate ready-made component for inline "what is this" affordances; do not hand-compose Tooltip around an info icon.

package/dist/skills/createui/rules/composition.md

@@ -1,6 +1,6 @@
 # Component Composition
 
-How Create UI components fit together. Compose primitives — never reroll a `<select>`, a custom callout, or a hand-styled loading button when a component already exists. Every component name below is in the `@createui` registry; add any of them with `npx @create-ui/cli add <name>`.
+How Create UI components fit together. Compose primitives - never reroll a `<select>`, a custom callout, or a hand-styled loading button when a component already exists. Every component name below is in the `@createui` registry; add any of them with `npx @create-ui/cli add <name>`.
 
 ## Contents
 
@@ -8,16 +8,16 @@ How Create UI components fit together. Compose primitives — never reroll a `<s
 - Callouts use InlineAlert
 - Toasts use the Toast component
 - Choosing between overlay components
-- Button has a `loading` prop — never hand-build a spinner button
+- Button has a `loading` prop - never hand-build a spinner button
 - Tabbed navigation uses TabMenu
-- Avatar always needs AvatarFallback
+- Avatar composition (AvatarText, not AvatarFallback)
 - Use existing components instead of custom markup
 
 ---
 
 ## Items always inside their Group component
 
-Never render menu/list items directly inside the content container — always wrap them in the matching `*Group`.
+Never render menu/list items directly inside the content container - always wrap them in the matching `*Group`.
 
 **Incorrect:**
 
@@ -42,17 +42,17 @@ Never render menu/list items directly inside the content container — always wr
 
 This applies to every group-based component:
 
-| Item | Group |
-|------|-------|
-| `SelectItem`, `SelectLabel` | `SelectGroup` |
-| `DropdownMenuItem`, `DropdownMenuLabel` | `DropdownMenuGroup` |
-| `CommandItem` | `CommandGroup` |
+| Item | Group | Requirement |
+|------|-------|-------------|
+| `SelectItem`, `SelectLabel` | `SelectGroup` | Structural - always wrap |
+| `CommandItem` | `CommandGroup` | Structural - always wrap |
+| `DropdownMenuItem`, `DropdownMenuLabel` | `DropdownMenuGroup` | Semantic - group related items (with `DropdownMenuLabel` / `DropdownMenuSeparator`); a lone item may sit directly in `DropdownMenuContent` |
 
 ---
 
 ## Callouts use InlineAlert
 
-Use `InlineAlert` for callouts. Don't hand-roll a styled `<div>` — and don't look for a shadcn-style generic alert (or a page-banner) component; `InlineAlert` is the callout primitive.
+Use `InlineAlert` for callouts. Don't hand-roll a styled `<div>` - and don't look for a shadcn-style generic alert (or a page-banner) component; `InlineAlert` is the callout primitive.
 
 **Incorrect:**
 
@@ -94,13 +94,13 @@ import {
 </InlineAlert>
 ```
 
-`InlineAlert` takes `variant` (`primary` | `neutral` | `danger` | `success` | `warning` | `info` | `away`) and `appearance` (`default` | `solid` | `soft` | `outline`). For a dismissible callout, add `<InlineAlertClose />` as a direct child and handle `onDismiss` on the root. For a full-width page banner, place an `InlineAlert` in a full-width container — there is no separate banner component.
+`InlineAlert` takes `variant` (`primary` | `neutral` | `danger` | `success` | `warning` | `info` | `away`) and `appearance` (`default` | `solid` | `soft` | `outline`). For a dismissible callout, add `<InlineAlertClose />` as a direct child and handle `onDismiss` on the root. For a full-width page banner, place an `InlineAlert` in a full-width container - there is no separate banner component.
 
 ---
 
 ## Toasts use the Toast component
 
-Toasts are the registry's own `toast` component — **not `sonner`**. There is no `toast()` function to import; compose the `Toast` parts and render it from your notification state.
+Toasts are the registry's own `toast` component - **not `sonner`**. There is no `toast()` function to import; compose the `Toast` parts and render it from your notification state.
 
 **Incorrect:**
 
@@ -140,7 +140,7 @@ import {
 
 `Toast` takes `variant` (`primary` | `neutral` | `danger` | `success` | `warning` | `info` | `away`) and `appearance` (`solid` | `soft` | `outline` | `default`), plus an `onDismiss` callback. Add `<ToastClose />` for an explicit close affordance and `<ToastProgress />` for an auto-dismiss countdown bar.
 
-There is no provider, queue, or stacking system — you own the notification state and the placement. Render active toasts from your state into a fixed container:
+There is no provider, queue, or stacking system - you own the notification state and the placement. Render active toasts from your state into a fixed container:
 
 ```tsx
 const [toasts, setToasts] = React.useState<AppToast[]>([])
@@ -168,7 +168,7 @@ const [toasts, setToasts] = React.useState<AppToast[]>([])
 
 ## Choosing between overlay components
 
-Pick the overlay that matches the interaction — these are the overlays that exist.
+Pick the overlay that matches the interaction - these are the overlays that exist.
 
 | Use case | Component |
 |----------|-----------|
@@ -177,13 +177,13 @@ Pick the overlay that matches the interaction — these are the overlays that ex
 | Action menu on a trigger | `DropdownMenu` |
 | Command palette / quick switcher | `Command` (inline) / `CommandDialog` (modal) |
 
-There is **no dialog, popover, sheet, drawer, alert-dialog, or hover-card component**. The only modal surface is `CommandDialog` (shipped with `command`). For other modal or contextual-panel needs, don't invent a lookalike from raw markup — surface the flow inline (e.g. an expanding section, a dedicated route, or an `InlineAlert` confirmation) or ask the user before hand-rolling an overlay.
+There is **no dialog, popover, sheet, drawer, alert-dialog, or hover-card component**. The only modal surface is `CommandDialog` (shipped with `command`). For other modal or contextual-panel needs, don't invent a lookalike from raw markup - surface the flow inline (e.g. an expanding section, a dedicated route, or an `InlineAlert` confirmation) or ask the user before hand-rolling an overlay.
 
 ---
 
-## Button has a `loading` prop — never hand-build a spinner button
+## Button has a `loading` prop - never hand-build a spinner button
 
-`Button` ships a real `loading` prop. It renders the `Spinner` and disables interaction for you — do not compose a `Spinner` + `disabled` button by hand.
+`Button` ships a real `loading` prop. It renders the `Spinner` and disables interaction for you - do not compose a `Spinner` + `disabled` button by hand.
 
 **Incorrect:**
 
@@ -200,7 +200,7 @@ There is **no dialog, popover, sheet, drawer, alert-dialog, or hover-card compon
 <Button loading>Saving…</Button>
 ```
 
-For icons, use the `leadingIcon` / `trailingIcon` props (or `iconOnly` for an icon-only button) — never wrap raw `<svg>` children or add sizing classes; the component sizes the icon per `size`.
+For icons, use the `leadingIcon` / `trailingIcon` props (or `iconOnly` for an icon-only button) - never wrap raw `<svg>` children or add sizing classes; the component sizes the icon per `size`.
 
 ```tsx
 import { RiSearchLine } from "@create-ui/assets/icons"
@@ -209,13 +209,13 @@ import { RiSearchLine } from "@create-ui/assets/icons"
 <Button iconOnly aria-label="Search" leadingIcon={<RiSearchLine />} />
 ```
 
-Remember the Button API: `variant` is `primary | neutral-solid | neutral-light | danger | success | inverse-solid | inverse-light`, and the outlined/ghost looks come from `appearance` (`solid | outline | ghost | soft`). There is no outline or destructive `variant` value — use `appearance="outline"` for the outlined look and `variant="danger"` for destructive actions. See `rules/styling.md` for the full variant/appearance reference.
+Remember the Button API: `variant` is `primary | neutral-solid | neutral-light | danger | success | inverse-solid | inverse-light`, and the outlined/ghost looks come from `appearance` (`solid | outline | ghost | soft`). There is no outline or destructive `variant` value - use `appearance="outline"` for the outlined look and `variant="danger"` for destructive actions. See `rules/styling.md` for the full variant/appearance reference.
 
 ---
 
 ## Tabbed navigation uses TabMenu
 
-Tabs are the `tab-menu` component — there is no shadcn-style tabs / tabs-list / tabs-trigger set. `TabMenu` wraps `TabMenuItem`s and owns the selection (`defaultValue`, or controlled `value` / `onValueChange`). It renders the menu only — render the active panel yourself from the value; there is no content component.
+Tabs are the `tab-menu` component - there is no shadcn-style tabs / tabs-list / tabs-trigger set. `TabMenu` wraps `TabMenuItem`s and owns the selection (`defaultValue`, or controlled `value` / `onValueChange`). It renders the menu only - render the active panel yourself from the value; there is no content component.
 
 ```tsx
 import { TabMenu, TabMenuItem } from "@/components/ui/tab-menu"
@@ -234,27 +234,43 @@ const [tab, setTab] = React.useState("overview")
 
 ---
 
-## Avatar always needs AvatarFallback
+## Avatar composition (AvatarText, not AvatarFallback)
 
-Always include `AvatarFallback` so something renders when the image is missing or fails to load.
+**`AvatarFallback` does not exist in Create UI** - the fallback/initials slot is `AvatarText`. It renders only while the sibling `AvatarImage` has not loaded (or when there is no image), so an image avatar should always carry one:
 
 ```tsx
+import { Avatar, AvatarImage, AvatarText } from "@/components/ui/avatar"
+
+<Avatar>
+  <AvatarImage src="/avatar.png" alt="User" />
+  <AvatarText>JD</AvatarText>
+</Avatar>
+```
+
+Initials-only avatars pick a real color `variant`; presence comes from `AvatarBadge` + `AvatarBadgeStatus`; stacks are `AvatarGroup` (+ `AvatarGroupAction` for the "+5" affordance):
+
+```tsx
+<Avatar variant="weak-blue"><AvatarText>YT</AvatarText></Avatar>
+
 <Avatar>
   <AvatarImage src="/avatar.png" alt="User" />
-  <AvatarFallback>JD</AvatarFallback>
+  <AvatarText>JD</AvatarText>
+  <AvatarBadge><AvatarBadgeStatus variant="online" /></AvatarBadge>
 </Avatar>
 ```
 
+See `reference/avatar.md` for the full prop tables (`size` `2xs`–`2xl`, `shape`, 55 color variants, `AvatarIcon`, `AvatarRing`).
+
 ---
 
 ## Use existing components instead of custom markup
 
-If a primitive already covers the job, use it — don't reach for raw elements or utility-class fakes.
+If a primitive already covers the job, use it - don't reach for raw elements or utility-class fakes.
 
 | Instead of | Use |
 |---|---|
 | `<hr>` or `<div className="border-t">` | `<Separator />` |
 | `<span className="rounded-full bg-green-100 …">` | `<Badge variant="success">Active</Badge>` |
-| A status dot built from a styled `<span>` | `<StatusBadge variant="success" />` (it renders the dot only — put the label next to it). `variant`: `primary`, `danger`, `success`, `warning`, `info`, `highlighted`, `away`, `verified`, `cyan`, `lime`, `neutral`, `white` — note `danger`, not `error` |
+| A status dot built from a styled `<span>` | `<StatusBadge variant="success" />` (it renders the dot only - put the label next to it). `variant`: `primary`, `danger`, `success`, `warning`, `info`, `highlighted`, `away`, `verified`, `cyan`, `lime`, `neutral`, `white` - note `danger`, not `error` |
 | A removable tag built from `<span>` + `<button>` | `<Chip onClose={…}>…</Chip>` |
 | A hand-rolled `animate-spin` loading indicator | `<Spinner />` |