@monkey-mini-app/ui 0.1.0 → 0.1.4

package/dist/src/components/dropdown-menu.tsx

@@ -6,6 +6,13 @@ import { Menu as MenuPrimitive } from "@base-ui/react/menu"
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { ChevronRightIcon, CheckIcon } from "lucide-react"
 
+/**
+ * Command menu on a trigger.
+ * @when Row `MoreHorizontal` actions. Free-form panel content → `Popover`.
+ * @example
+ * <DropdownMenu><DropdownMenuTrigger asChild><Button><Icon.MoreHorizontal /></Button></DropdownMenuTrigger><DropdownMenuContent><DropdownMenuItem onClick={edit}>编辑</DropdownMenuItem></DropdownMenuContent></DropdownMenu>
+ * @family Navigation
+ */
 function DropdownMenu({ ...props }: MenuPrimitive.Root.Props) {
   return <MenuPrimitive.Root data-slot="dropdown-menu" {...props} />
 }

package/dist/src/components/empty.tsx

@@ -2,6 +2,13 @@ import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Empty-state block: media + title + description + action.
+ * @when Any list/panel with no rows — pair media with an `Illu*`.
+ * @example
+ * <Empty><EmptyHeader><EmptyMedia variant="icon"><IlluEmpty /></EmptyMedia><EmptyTitle>还没有数据</EmptyTitle><EmptyDescription>点右上角添加</EmptyDescription></EmptyHeader></Empty>
+ * @family Feedback & status
+ */
 function Empty({
   className,
   title,

package/dist/src/components/field.tsx

@@ -67,6 +67,12 @@ const fieldVariants = cva(
   }
 )
 
+/**
+ * @family Form
+ * @when Any form row that must read well and stay accessible.
+ * @example
+ * <Field><FieldLabel htmlFor="n">名称</FieldLabel><Input id="n" /><FieldDescription>显示在列表里</FieldDescription></Field>
+ */
 function Field({
   className,
   orientation = "vertical",

package/dist/src/components/hover-card.tsx

@@ -2,6 +2,10 @@ import { PreviewCard as PreviewCardPrimitive } from "@base-ui/react/preview-card
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * @family Surface
+ * @when Peek a user/issue without navigating. Needs a decision → `Dialog`.
+ */
 function HoverCard({ ...props }: PreviewCardPrimitive.Root.Props) {
   return <PreviewCardPrimitive.Root data-slot="hover-card" {...props} />
 }

package/dist/src/components/input-group.tsx

@@ -8,6 +8,10 @@ import { Button } from "@monkey-mini-app/ui/components/button"
 import { Input } from "@monkey-mini-app/ui/components/input"
 import { Textarea } from "@monkey-mini-app/ui/components/textarea"
 
+/**
+ * @family Form
+ * @when Search/url/amount fields with adornments; keep validation in `NumberField` etc.
+ */
 function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div

package/dist/src/components/input.tsx

@@ -3,6 +3,13 @@ import { Input as InputPrimitive } from "@base-ui/react/input"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Single-line text input.
+ * @when Plain text. Numbers → `NumberField`; secrets → `PasswordField`; search → `SearchInput`.
+ * @example
+ * <Input value={v} onChange={(e) => set(e.target.value)} placeholder="名称" />
+ * @family Form
+ */
 function Input({ className, type, ...props }: React.ComponentProps<"input">) {
   return (
     <InputPrimitive

package/dist/src/components/item.tsx

@@ -56,6 +56,10 @@ const itemVariants = cva(
   }
 )
 
+/**
+ * @family Layout & structure
+ * @when A uniform list row when `DataGrid` is too heavy.
+ */
 function Item({
   className,
   variant = "default",

package/dist/src/components/kbd.tsx

@@ -1,5 +1,9 @@
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * @family Layout & structure
+ * @when Documenting ⌘K-style shortcuts in help panels.
+ */
 function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
   return (
     <kbd

package/dist/src/components/label.tsx

@@ -4,6 +4,13 @@ import * as React from "react"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Accessible field label.
+ * @when Always bind `htmlFor` — bare text labels are not accessible.
+ * @example
+ * <Label htmlFor="name">名称</Label>
+ * @family Form
+ */
 function Label({ className, ...props }: React.ComponentProps<"label">) {
   return (
     <label

package/dist/src/components/marker.tsx

@@ -19,6 +19,10 @@ const markerVariants = cva(
   }
 )
 
+/**
+ * @family Layout & structure
+ * @when Small state markers inside a sentence or legend.
+ */
 function Marker({
   className,
   variant = "default",

package/dist/src/components/menubar.tsx

@@ -22,6 +22,10 @@ import {
 } from "@monkey-mini-app/ui/components/dropdown-menu"
 import { CheckIcon } from "lucide-react"
 
+/**
+ * @family Navigation
+ * @when Rarely right for a panel-width mini-app — prefer `Tabs` / `DropdownMenu`.
+ */
 function Menubar({ className, ...props }: MenubarPrimitive.Props) {
   return (
     <MenubarPrimitive

package/dist/src/components/message-scroller.tsx

@@ -16,6 +16,10 @@ function MessageScrollerProvider(
   return <MessageScrollerPrimitive.Provider {...props} />
 }
 
+/**
+ * @family Realtime
+ * @when Streaming chat output. Logs by timestamp → `LogViewer`.
+ */
 function MessageScroller({
   className,
   ...props

package/dist/src/components/message.tsx

@@ -12,6 +12,10 @@ function MessageGroup({ className, ...props }: React.ComponentProps<"div">) {
   )
 }
 
+/**
+ * @family Surface
+ * @when Assistant/user turns. Timestamped log rows → `LogViewer`.
+ */
 function Message({
   className,
   align = "start",

package/dist/src/components/native-select.tsx

@@ -7,6 +7,10 @@ type NativeSelectProps = Omit<React.ComponentProps<"select">, "size"> & {
   size?: "sm" | "default"
 }
 
+/**
+ * @family Form
+ * @when Short option lists where a plain select is enough and `Select` is overkill.
+ */
 function NativeSelect({
   className,
   size = "default",

package/dist/src/components/navigation-menu.tsx

@@ -4,6 +4,10 @@ import { cva } from "class-variance-authority"
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { ChevronDownIcon } from "lucide-react"
 
+/**
+ * @family Navigation
+ * @when Not for mini-apps with one screen — use `Tabs` or `AppShell` sidebar.
+ */
 function NavigationMenu({
   align = "start",
   className,

package/dist/src/components/pagination.tsx

@@ -7,6 +7,10 @@ import { useLabels } from "@monkey-mini-app/ui/i18n/context"
 import { Button } from "@monkey-mini-app/ui/components/button"
 import { ChevronLeftIcon, ChevronRightIcon, MoreHorizontalIcon } from "lucide-react"
 
+/**
+ * @family Navigation
+ * @when Only when you page by hand; `DataGrid` does this itself.
+ */
 function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
   return (
     <nav

package/dist/src/components/popover.tsx

@@ -3,6 +3,13 @@ import { Popover as PopoverPrimitive } from "@base-ui/react/popover"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Anchored floating panel.
+ * @when Small editor/filter anchored to a control. Menus of commands → `DropdownMenu`.
+ * @example
+ * <Popover><PopoverTrigger asChild><Button>筛选</Button></PopoverTrigger><PopoverContent>…</PopoverContent></Popover>
+ * @family Surface
+ */
 function Popover({ ...props }: PopoverPrimitive.Root.Props) {
   return <PopoverPrimitive.Root data-slot="popover" {...props} />
 }

package/dist/src/components/progress.tsx

@@ -4,6 +4,13 @@ import { Progress as ProgressPrimitive } from "@base-ui/react/progress"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Linear determinate progress bar.
+ * @when Full-width scan/import progress. Compact circle → `ProgressRing`.
+ * @example
+ * <Progress value={scan.progress} />
+ * @family Feedback & status
+ */
 function Progress({
   className,
   children,

package/dist/src/components/questionnaire.tsx

@@ -8,6 +8,10 @@ import { useLabels } from "@monkey-mini-app/ui/i18n/context"
 import { buttonVariants, type Button } from "@monkey-mini-app/ui/components/button"
 import { CheckIcon } from "lucide-react"
 
+/**
+ * @family Form
+ * @when Structured ask-the-user blocks; you persist the answers.
+ */
 function Questionnaire({
   className,
   ...props

package/dist/src/components/radio-group.tsx

@@ -3,6 +3,10 @@ import { RadioGroup as RadioGroupPrimitive } from "@base-ui/react/radio-group"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * @family Form
+ * @when 2–5 mutually exclusive options. Many options → `Select`.
+ */
 function RadioGroup({ className, ...props }: RadioGroupPrimitive.Props) {
   return (
     <RadioGroupPrimitive

package/dist/src/components/resizable.tsx

@@ -4,6 +4,13 @@ import * as ResizablePrimitive from "react-resizable-panels"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Draggable split panes.
+ * @family Layout & structure
+ * @when Master-detail or editor + preview inside the app body.
+ * @example
+ * <ResizablePanelGroup orientation="horizontal"><ResizablePanel>list</ResizablePanel><ResizableHandle /><ResizablePanel>detail</ResizablePanel></ResizablePanelGroup>
+ */
 function ResizablePanelGroup({
   className,
   ...props

package/dist/src/components/scroll-area.tsx

@@ -2,6 +2,10 @@ import { ScrollArea as ScrollAreaPrimitive } from "@base-ui/react/scroll-area"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * @family Layout & structure
+ * @when A bounded panel (list in a card). Whole-page scroll → plain div.
+ */
 function ScrollArea({
   className,
   children,

package/dist/src/components/select.tsx

@@ -6,6 +6,13 @@ import { Select as SelectPrimitive } from "@base-ui/react/select"
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { ChevronDownIcon, CheckIcon, ChevronUpIcon } from "lucide-react"
 
+/**
+ * Dropdown single-choice from a fixed list.
+ * @when Closed set of options (searchable/large → `Autocomplete` or `DataGrid` filter).
+ * @example
+ * <Select value={v} onValueChange={set}><SelectTrigger><SelectValue placeholder="选择" /></SelectTrigger><SelectContent><SelectItem value="a">A</SelectItem></SelectContent></Select>
+ * @family Form
+ */
 const Select = SelectPrimitive.Root
 
 function SelectGroup({ className, ...props }: SelectPrimitive.Group.Props) {

package/dist/src/components/separator.tsx

@@ -2,6 +2,11 @@ import { Separator as SeparatorPrimitive } from "@base-ui/react/separator"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Horizontal/vertical rule.
+ * @when Grouping inside panels.
+ * @family Layout & structure
+ */
 function Separator({
   className,
   orientation = "horizontal",

package/dist/src/components/sheet.tsx

@@ -5,6 +5,13 @@ import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { Button } from "@monkey-mini-app/ui/components/button"
 import { XIcon } from "lucide-react"
 
+/**
+ * Slide-in side panel.
+ * @when Detail/edit panel that keeps the list visible — the usual master-detail pattern. Size it with `width` on `SheetContent`: the panel carries its own `data-[side=right]:sm:max-w-sm` / `data-[side=left]:sm:max-w-sm`, so a `max-w-*` in `className` loses at ≥sm (inline style or `!max-w-*` also work).
+ * @example
+ * <Sheet open={open} onOpenChange={setOpen}><SheetContent side="right"><SheetHeader><SheetTitle>详情</SheetTitle></SheetHeader>…</SheetContent></Sheet>
+ * @family Surface
+ */
 function Sheet({ ...props }: SheetPrimitive.Root.Props) {
   return <SheetPrimitive.Root data-slot="sheet" {...props} />
 }
@@ -39,17 +46,32 @@ function SheetContent({
   children,
   side = "right",
   showCloseButton = true,
+  width,
+  style,
   ...props
 }: SheetPrimitive.Popup.Props & {
   side?: "top" | "right" | "bottom" | "left"
   showCloseButton?: boolean
+  /**
+   * Panel width — a number is px. Applied as inline `maxWidth` on purpose: the base class
+   * already caps the sheet at `sm:max-w-sm` through a variant selector, which outranks a
+   * `max-w-*` utility the caller passes in `className`, so a prop is the only honest door.
+   */
+  width?: string | number
 }) {
+  const maxWidth =
+    width == null
+      ? undefined
+      : typeof width === "number"
+        ? `${width}px`
+        : width
   return (
     <SheetPortal>
       <SheetOverlay />
       <SheetPrimitive.Popup
         data-slot="sheet-content"
         data-side={side}
+        style={maxWidth == null ? style : { ...style, maxWidth }}
         className={cn(
           "fixed z-50 flex flex-col gap-4 bg-popover bg-clip-padding text-sm text-popover-foreground shadow-lg transition duration-200 ease-in-out data-ending-style:opacity-0 data-starting-style:opacity-0 data-[side=bottom]:inset-x-0 data-[side=bottom]:bottom-0 data-[side=bottom]:h-auto data-[side=bottom]:border-t data-[side=bottom]:data-ending-style:translate-y-[2.5rem] data-[side=bottom]:data-starting-style:translate-y-[2.5rem] data-[side=left]:inset-y-0 data-[side=left]:left-0 data-[side=left]:h-full data-[side=left]:w-3/4 data-[side=left]:border-r data-[side=left]:data-ending-style:translate-x-[-2.5rem] data-[side=left]:data-starting-style:translate-x-[-2.5rem] data-[side=right]:inset-y-0 data-[side=right]:right-0 data-[side=right]:h-full data-[side=right]:w-3/4 data-[side=right]:border-l data-[side=right]:data-ending-style:translate-x-[2.5rem] data-[side=right]:data-starting-style:translate-x-[2.5rem] data-[side=top]:inset-x-0 data-[side=top]:top-0 data-[side=top]:h-auto data-[side=top]:border-b data-[side=top]:data-ending-style:translate-y-[-2.5rem] data-[side=top]:data-starting-style:translate-y-[-2.5rem] data-[side=left]:sm:max-w-sm data-[side=right]:sm:max-w-sm",
           className

package/dist/src/components/sidebar.tsx

@@ -147,6 +147,10 @@ function SidebarProvider({
   )
 }
 
+/**
+ * @family Navigation
+ * @when Many sections in one app; `AppShell` already wires one for you.
+ */
 function Sidebar({
   side = "left",
   variant = "sidebar",

package/dist/src/components/skeleton.tsx

@@ -1,5 +1,12 @@
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Pulse placeholder block.
+ * @when First paint while `call()` is pending — match the real layout's size.
+ * @example
+ * <div className="flex flex-col gap-2">{[0,1,2].map((i) => <Skeleton key={i} className="h-16 w-full" />)}</div>
+ * @family Feedback & status
+ */
 function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div

package/dist/src/components/slider.tsx

@@ -2,6 +2,10 @@ import { Slider as SliderPrimitive } from "@base-ui/react/slider"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * @family Form
+ * @when One numeric value. Range → `SliderRange`.
+ */
 function Slider({
   className,
   defaultValue,

package/dist/src/components/spinner.tsx

@@ -1,6 +1,12 @@
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { Loader2Icon } from "lucide-react"
 
+/**
+ * @family Feedback & status
+ * @when Inside a button while `call()` is pending. Known % → `Progress`.
+ * @example
+ * <Button disabled><Spinner /> 保存中</Button>
+ */
 function Spinner({ className, ...props }: React.ComponentProps<"svg">) {
   return (
     <Loader2Icon data-slot="spinner" role="status" aria-label="Loading" className={cn("size-4 animate-spin", className)} {...props} />

package/dist/src/components/switch.tsx

@@ -4,6 +4,13 @@ import { Switch as SwitchPrimitive } from "@base-ui/react/switch"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Boolean toggle.
+ * @when Immediate on/off settings (submit-on-toggle).
+ * @example
+ * <Switch checked={on} onCheckedChange={set} />
+ * @family Form
+ */
 function Switch({
   className,
   size = "default",

package/dist/src/components/table.tsx

@@ -2,6 +2,13 @@ import * as React from "react"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Raw HTML table primitives.
+ * @when Only when you need full control of cells. Otherwise use `DataGrid` (sorting/filter/paging/CSV built in).
+ * @example
+ * <Table><TableHeader><TableRow><TableHead>列</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>v</TableCell></TableRow></TableBody></Table>
+ * @family Data & tables
+ */
 function Table({ className, ...props }: React.ComponentProps<"table">) {
   return (
     <div

package/dist/src/components/tabs.tsx

@@ -5,6 +5,13 @@ import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Switch between views in one page.
+ * @when Board vs table, or settings sections. Navigation between routes/pages → keep it in your own state.
+ * @example
+ * <Tabs value={v} onValueChange={set}><TabsList><TabsTrigger value="a">A</TabsTrigger></TabsList><TabsContent value="a">…</TabsContent></Tabs>
+ * @family Navigation
+ */
 function Tabs({
   className,
   orientation = "horizontal",

package/dist/src/components/textarea.tsx

@@ -2,6 +2,13 @@ import * as React from "react"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Multi-line text input.
+ * @when Notes/prompts. Code → `CodeEditor`; markdown → `MarkdownEditor`.
+ * @example
+ * <Textarea rows={4} value={v} onChange={(e) => set(e.target.value)} />
+ * @family Form
+ */
 function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
   return (
     <textarea

package/dist/src/components/toast.tsx

@@ -30,6 +30,13 @@ function ToastViewport({ className, ...props }: ToastPrimitive.Viewport.Props) {
   )
 }
 
+/**
+ * Transient notification (provider + viewport + `toast()`).
+ * @when Confirm/save failures. The host already mounts the provider — call `toast(...)`.
+ * @example
+ * toast({ title: "已保存", description: "2 条更新" })
+ * @family Feedback & status
+ */
 function Toast({ className, ...props }: ToastPrimitive.Root.Props) {
   return (
     <ToastPrimitive.Root

package/dist/src/components/toggle-group.tsx

@@ -20,6 +20,10 @@ const ToggleGroupContext = React.createContext<
   orientation: "horizontal",
 })
 
+/**
+ * @family Form
+ * @when Multiple independent on/off buttons; exclusive selection → `Tabs`/`ButtonGroup`.
+ */
 function ToggleGroup({
   className,
   variant,

package/dist/src/components/toggle.tsx

@@ -25,6 +25,10 @@ const toggleVariants = cva(
   }
 )
 
+/**
+ * @family Form
+ * @when Binary formatting switch (bold, filters on).
+ */
 function Toggle({
   className,
   variant = "default",

package/dist/src/components/tooltip.tsx

@@ -17,6 +17,13 @@ function TooltipProvider({
   )
 }
 
+/**
+ * Hover/focus hint on an icon or truncated label.
+ * @when Explaining an icon-only button. Never put an action in it.
+ * @example
+ * <Tooltip><TooltipTrigger asChild><Button size="icon" aria-label="刷新"><Icon.RefreshCw /></Button></TooltipTrigger><TooltipContent>刷新</TooltipContent></Tooltip>
+ * @family Surface
+ */
 function Tooltip({ ...props }: TooltipPrimitive.Root.Props) {
   return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
 }

package/dist/src/composites/autocomplete.tsx

@@ -4,6 +4,13 @@ import * as React from "react"
 
 import { Input } from "@monkey-mini-app/ui/components/input"
 
+/**
+ * Text input with filtered suggestions.
+ * @when Free text allowed but known values should be suggested. Strict pick-list → `Select`.
+ * @example
+ * <Autocomplete options={["main", "develop"]} onChange={(v) => set(v)} />
+ * @family Form
+ */
 export function Autocomplete({
   value,
   onChange,

package/dist/src/composites/cascader.tsx

@@ -4,6 +4,13 @@ import { NativeSelect, NativeSelectOption } from "@monkey-mini-app/ui/components
 
 export type CascaderNode = { value: string; label: string; children?: CascaderNode[] }
 
+/**
+ * Multi-level drill-down picker.
+ * @when Hierarchical codes (region → site → line). Flat tree → `TreeView`.
+ * @example
+ * <Cascader options={[{ label: "华东", value: "cn", children: [{ label: "上海", value: "sha" }] }]} onChange={(v) => set(v)} />
+ * @family Form
+ */
 export function Cascader({
   options,
   value = [],

package/dist/src/composites/color-picker.tsx

@@ -1,5 +1,12 @@
 "use client"
 
+/**
+ * Swatch + hex colour input.
+ * @when Theme/label colour config. Never for secrets.
+ * @example
+ * <ColorPicker value={c} onChange={(v) => set(v)} />
+ * @family Form
+ */
 export function ColorPicker({
   value = "#111111",
   onChange,

package/dist/src/composites/confirm-dialog.tsx

@@ -12,6 +12,13 @@ import {
 } from "@monkey-mini-app/ui/components/alert-dialog"
 import { useLabels } from "@monkey-mini-app/ui/i18n/context"
 
+/**
+ * Controlled yes/no dialog with loading-safe confirm.
+ * @when Any destructive action. Needs a form inside → compose `Dialog` yourself.
+ * @example
+ * <ConfirmDialog open={open} title="删除这条？" onConfirm={remove} onOpenChange={setOpen} />
+ * @family Surface
+ */
 export function ConfirmDialog({
   open,
   onOpenChange,

package/dist/src/composites/copyable.tsx

@@ -10,7 +10,15 @@ import {
   InputGroupInput,
 } from "@monkey-mini-app/ui/components/input-group"
 import { useLabels } from "@monkey-mini-app/ui/i18n/context"
+import { writeClipboard } from "@monkey-mini-app/ui/lib/clipboard"
 
+/**
+ * Inline text with a copy button.
+ * @when IDs, hashes, URLs, tokens the user pastes elsewhere.
+ * @example
+ * <Copyable value="i_1724918400" />
+ * @family Discovery & inspect
+ */
 export function Copyable({ value }: { value: string }) {
   const t = useLabels("copyable")
   const [copied, setCopied] = React.useState(false)
@@ -24,7 +32,7 @@ export function Copyable({ value }: { value: string }) {
           type="button"
           aria-label={t.copy}
           onClick={async () => {
-            await navigator.clipboard.writeText(value)
+            if (!(await writeClipboard(value))) return
             setCopied(true)
             window.setTimeout(() => setCopied(false), 1200)
           }}

package/dist/src/composites/currency-input.tsx

@@ -7,6 +7,13 @@ import {
   InputGroupText,
 } from "@monkey-mini-app/ui/components/input-group"
 
+/**
+ * Amount input with grouping + currency prefix.
+ * @when Money fields; keeps the raw string out of your state.
+ * @example
+ * <CurrencyInput currency="CNY" onChange={(v) => set(v)} />
+ * @family Form
+ */
 export function CurrencyInput({
   value,
   onChange,

package/dist/src/composites/date-picker.tsx

@@ -23,6 +23,13 @@ export type DatePickerProps = {
   className?: string
 }
 
+/**
+ * Single calendar date (day precision).
+ * @when Filtering or storing one day. With a clock → `DateTimePicker`.
+ * @example
+ * <DatePicker value={d} onChange={(v) => set(v)} />
+ * @family Calendar & date
+ */
 export function DatePicker({
   value,
   onChange,