@auto-engineer/generate-react-client 1.34.0 → 1.36.0

package/dist/starter/src/components/ui/ContextMenu.tsx

@@ -6,30 +6,37 @@ import { ContextMenu as ContextMenuPrimitive } from 'radix-ui';
 
 import { cn } from '@/lib/utils';
 
+/** Right-click menu with keyboard navigation. Supports submenus, checkbox/radio items, separators, and shortcuts. */
 function ContextMenu({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Root>) {
   return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />;
 }
 
+/** The element that opens the context menu on right-click. Wraps its children. */
 function ContextMenuTrigger({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Trigger>) {
   return <ContextMenuPrimitive.Trigger data-slot="context-menu-trigger" {...props} />;
 }
 
+/** Groups related context menu items for accessibility. */
 function ContextMenuGroup({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Group>) {
   return <ContextMenuPrimitive.Group data-slot="context-menu-group" {...props} />;
 }
 
+/** Renders context menu content into a React portal. */
 function ContextMenuPortal({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Portal>) {
   return <ContextMenuPrimitive.Portal data-slot="context-menu-portal" {...props} />;
 }
 
+/** Container for a submenu within the context menu. */
 function ContextMenuSub({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Sub>) {
   return <ContextMenuPrimitive.Sub data-slot="context-menu-sub" {...props} />;
 }
 
+/** Groups radio items for single-selection within the context menu. */
 function ContextMenuRadioGroup({ ...props }: React.ComponentProps<typeof ContextMenuPrimitive.RadioGroup>) {
   return <ContextMenuPrimitive.RadioGroup data-slot="context-menu-radio-group" {...props} />;
 }
 
+/** Menu item that opens a nested submenu on hover or keyboard navigation. Shows a chevron indicator. */
 function ContextMenuSubTrigger({
   className,
   inset,
@@ -54,6 +61,7 @@ function ContextMenuSubTrigger({
   );
 }
 
+/** Popup content for a nested submenu. */
 function ContextMenuSubContent({ className, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.SubContent>) {
   return (
     <ContextMenuPrimitive.SubContent
@@ -67,6 +75,7 @@ function ContextMenuSubContent({ className, ...props }: React.ComponentProps<typ
   );
 }
 
+/** The positioned popup container for context menu items. Portals to the document body. */
 function ContextMenuContent({ className, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Content>) {
   return (
     <ContextMenuPrimitive.Portal>
@@ -82,9 +91,15 @@ function ContextMenuContent({ className, ...props }: React.ComponentProps<typeof
   );
 }
 
+/**
+ * A selectable action within the context menu.
+ * Use variant="destructive" for dangerous actions like delete.
+ */
 function ContextMenuItem({
   className,
+  /** Adds left padding to align with items that have icons or indicators. */
   inset,
+  /** Use "destructive" for dangerous actions. */
   variant = 'default',
   ...props
 }: React.ComponentProps<typeof ContextMenuPrimitive.Item> & {
@@ -105,6 +120,7 @@ function ContextMenuItem({
   );
 }
 
+/** A toggleable checkbox item within the context menu. Shows a check indicator when active. */
 function ContextMenuCheckboxItem({
   className,
   children,
@@ -131,6 +147,7 @@ function ContextMenuCheckboxItem({
   );
 }
 
+/** A radio-selectable item within a ContextMenuRadioGroup. Shows a dot indicator when selected. */
 function ContextMenuRadioItem({
   className,
   children,
@@ -155,6 +172,7 @@ function ContextMenuRadioItem({
   );
 }
 
+/** Non-interactive label within a context menu, used for section headings. */
 function ContextMenuLabel({
   className,
   inset,
@@ -172,6 +190,7 @@ function ContextMenuLabel({
   );
 }
 
+/** Visual divider between groups of context menu items. */
 function ContextMenuSeparator({ className, ...props }: React.ComponentProps<typeof ContextMenuPrimitive.Separator>) {
   return (
     <ContextMenuPrimitive.Separator
@@ -182,6 +201,7 @@ function ContextMenuSeparator({ className, ...props }: React.ComponentProps<type
   );
 }
 
+/** Displays a keyboard shortcut hint aligned to the right side of a context menu item. */
 function ContextMenuShortcut({ className, ...props }: React.ComponentProps<'span'>) {
   return (
     <span

package/dist/starter/src/components/ui/Dialog.stories.tsx

@@ -19,6 +19,7 @@ const meta: Meta<typeof Dialog> = {
 export default meta;
 type Story = StoryObj<typeof Dialog>;
 
+/** Shows a dialog with a form for editing profile information. */
 export const Default: Story = {
   render: () => (
     <Dialog>
@@ -52,6 +53,7 @@ export const Default: Story = {
   ),
 };
 
+/** Shows a confirmation dialog with a footer close button and a destructive action. */
 export const WithCloseButton: Story = {
   render: () => (
     <Dialog>

package/dist/starter/src/components/ui/Dialog.tsx

@@ -5,22 +5,27 @@ import { Dialog as DialogPrimitive } from 'radix-ui';
 import { cn } from '@/lib/utils';
 import { Button } from '@/components/ui/Button';
 
+/** A modal overlay with focus trapping and scroll locking. Click outside or press Escape to close. */
 function Dialog({ ...props }: React.ComponentProps<typeof DialogPrimitive.Root>) {
   return <DialogPrimitive.Root data-slot="dialog" {...props} />;
 }
 
+/** Button or element that opens the dialog when clicked. */
 function DialogTrigger({ ...props }: React.ComponentProps<typeof DialogPrimitive.Trigger>) {
   return <DialogPrimitive.Trigger data-slot="dialog-trigger" {...props} />;
 }
 
+/** Renders dialog content into a React portal. */
 function DialogPortal({ ...props }: React.ComponentProps<typeof DialogPrimitive.Portal>) {
   return <DialogPrimitive.Portal data-slot="dialog-portal" {...props} />;
 }
 
+/** Programmatic close trigger for the dialog. */
 function DialogClose({ ...props }: React.ComponentProps<typeof DialogPrimitive.Close>) {
   return <DialogPrimitive.Close data-slot="dialog-close" {...props} />;
 }
 
+/** Semi-transparent backdrop behind the dialog that dims the page content. */
 function DialogOverlay({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Overlay>) {
   return (
     <DialogPrimitive.Overlay
@@ -34,9 +39,14 @@ function DialogOverlay({ className, ...props }: React.ComponentProps<typeof Dial
   );
 }
 
+/**
+ * The main dialog panel centered on screen with overlay backdrop.
+ * Set showCloseButton={false} to hide the top-right X button.
+ */
 function DialogContent({
   className,
   children,
+  /** Whether to render the close (X) button in the top-right corner. */
   showCloseButton = true,
   ...props
 }: React.ComponentProps<typeof DialogPrimitive.Content> & {
@@ -68,6 +78,7 @@ function DialogContent({
   );
 }
 
+/** Container for DialogTitle and DialogDescription at the top of the dialog. */
 function DialogHeader({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -78,8 +89,13 @@ function DialogHeader({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/**
+ * Container for action buttons at the bottom of the dialog.
+ * Set showCloseButton to add an automatic "Close" button.
+ */
 function DialogFooter({
   className,
+  /** Whether to append a "Close" button that dismisses the dialog. */
   showCloseButton = false,
   children,
   ...props
@@ -102,6 +118,7 @@ function DialogFooter({
   );
 }
 
+/** Accessible title for the dialog. Required for screen reader support. */
 function DialogTitle({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Title>) {
   return (
     <DialogPrimitive.Title
@@ -112,6 +129,7 @@ function DialogTitle({ className, ...props }: React.ComponentProps<typeof Dialog
   );
 }
 
+/** Accessible description text for the dialog, displayed below the title. */
 function DialogDescription({ className, ...props }: React.ComponentProps<typeof DialogPrimitive.Description>) {
   return (
     <DialogPrimitive.Description

package/dist/starter/src/components/ui/Direction.stories.tsx

@@ -13,6 +13,7 @@ function DirectionDisplay() {
   return <p className="text-sm text-muted-foreground">Current direction: {direction ?? 'not set'}</p>;
 }
 
+/** Shows the DirectionProvider in left-to-right mode. */
 export const LTR: Story = {
   render: () => (
     <DirectionProvider dir="ltr">
@@ -24,6 +25,7 @@ export const LTR: Story = {
   ),
 };
 
+/** Shows the DirectionProvider in right-to-left mode for internationalization support. */
 export const RTL: Story = {
   render: () => (
     <DirectionProvider dir="rtl">

package/dist/starter/src/components/ui/Direction.tsx

@@ -3,8 +3,13 @@
 import * as React from 'react';
 import { Direction } from 'radix-ui';
 
+/**
+ * Provides text direction (LTR/RTL) context to all descendant Radix UI components.
+ * Accepts either `dir` or `direction` prop for convenience.
+ */
 function DirectionProvider({
   dir,
+  /** Alias for `dir`. If both are provided, `direction` takes precedence. */
   direction,
   children,
 }: React.ComponentProps<typeof Direction.DirectionProvider> & {
@@ -13,6 +18,7 @@ function DirectionProvider({
   return <Direction.DirectionProvider dir={direction ?? dir}>{children}</Direction.DirectionProvider>;
 }
 
+/** Hook to read the current text direction from the nearest DirectionProvider. */
 const useDirection = Direction.useDirection;
 
 export { DirectionProvider, useDirection };

package/dist/starter/src/components/ui/Drawer.stories.tsx

@@ -18,6 +18,7 @@ const meta: Meta<typeof Drawer> = {
 export default meta;
 type Story = StoryObj<typeof Drawer>;
 
+/** Shows a bottom drawer with a title, description, body content, and action buttons. */
 export const Default: Story = {
   render: () => (
     <Drawer>
@@ -43,6 +44,7 @@ export const Default: Story = {
   ),
 };
 
+/** Shows a drawer sliding in from the right side, useful for side panels and detail views. */
 export const RightSide: Story = {
   render: () => (
     <Drawer direction="right">

package/dist/starter/src/components/ui/Drawer.tsx

@@ -3,22 +3,32 @@ import { Drawer as DrawerPrimitive } from 'vaul';
 
 import { cn } from '@/lib/utils';
 
+/**
+ * A panel that slides in from the edge of the screen, ideal for mobile-friendly interactions.
+ * Built on Vaul with swipe-to-dismiss gestures. Supports top, bottom, left, and right directions.
+ *
+ * Compose with DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, and DrawerFooter.
+ */
 function Drawer({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Root>) {
   return <DrawerPrimitive.Root data-slot="drawer" {...props} />;
 }
 
+/** Button or element that opens the drawer when clicked. */
 function DrawerTrigger({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Trigger>) {
   return <DrawerPrimitive.Trigger data-slot="drawer-trigger" {...props} />;
 }
 
+/** Renders drawer content into a React portal. */
 function DrawerPortal({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Portal>) {
   return <DrawerPrimitive.Portal data-slot="drawer-portal" {...props} />;
 }
 
+/** Programmatic close trigger for the drawer. */
 function DrawerClose({ ...props }: React.ComponentProps<typeof DrawerPrimitive.Close>) {
   return <DrawerPrimitive.Close data-slot="drawer-close" {...props} />;
 }
 
+/** Semi-transparent backdrop behind the drawer that dims the page content. */
 function DrawerOverlay({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Overlay>) {
   return (
     <DrawerPrimitive.Overlay
@@ -32,6 +42,10 @@ function DrawerOverlay({ className, ...props }: React.ComponentProps<typeof Draw
   );
 }
 
+/**
+ * The main drawer panel that slides in from the configured direction.
+ * Automatically shows a drag handle for bottom drawers.
+ */
 function DrawerContent({ className, children, ...props }: React.ComponentProps<typeof DrawerPrimitive.Content>) {
   return (
     <DrawerPortal data-slot="drawer-portal">
@@ -55,6 +69,7 @@ function DrawerContent({ className, children, ...props }: React.ComponentProps<t
   );
 }
 
+/** Container for DrawerTitle and DrawerDescription at the top of the drawer. */
 function DrawerHeader({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -68,10 +83,12 @@ function DrawerHeader({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** Container for action buttons at the bottom of the drawer. */
 function DrawerFooter({ className, ...props }: React.ComponentProps<'div'>) {
   return <div data-slot="drawer-footer" className={cn('mt-auto flex flex-col gap-2 p-4', className)} {...props} />;
 }
 
+/** Accessible title for the drawer. */
 function DrawerTitle({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Title>) {
   return (
     <DrawerPrimitive.Title
@@ -82,6 +99,7 @@ function DrawerTitle({ className, ...props }: React.ComponentProps<typeof Drawer
   );
 }
 
+/** Accessible description text for the drawer, displayed below the title. */
 function DrawerDescription({ className, ...props }: React.ComponentProps<typeof DrawerPrimitive.Description>) {
   return (
     <DrawerPrimitive.Description

package/dist/starter/src/components/ui/DropdownMenu.stories.tsx

@@ -19,6 +19,7 @@ const meta: Meta<typeof DropdownMenu> = {
 export default meta;
 type Story = StoryObj<typeof DropdownMenu>;
 
+/** Shows a dropdown menu with grouped items, icons, keyboard shortcuts, and a destructive logout action. */
 export const Default: Story = {
   render: () => (
     <DropdownMenu>
@@ -55,6 +56,7 @@ export const Default: Story = {
   ),
 };
 
+/** Shows a minimal dropdown menu with basic edit/duplicate/delete actions. */
 export const Simple: Story = {
   render: () => (
     <DropdownMenu>

package/dist/starter/src/components/ui/DropdownMenu.tsx

@@ -6,18 +6,22 @@ import { DropdownMenu as DropdownMenuPrimitive } from 'radix-ui';
 
 import { cn } from '@/lib/utils';
 
+/** Action menu triggered by a button click. Supports submenus, checkbox/radio items, and keyboard shortcuts. */
 function DropdownMenu({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {
   return <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />;
 }
 
+/** Renders dropdown menu content into a React portal. */
 function DropdownMenuPortal({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
   return <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />;
 }
 
+/** Button or element that toggles the dropdown menu open/closed. */
 function DropdownMenuTrigger({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
   return <DropdownMenuPrimitive.Trigger data-slot="dropdown-menu-trigger" {...props} />;
 }
 
+/** The positioned popup container for dropdown menu items. Portals to the document body. */
 function DropdownMenuContent({
   className,
   sideOffset = 4,
@@ -38,13 +42,20 @@ function DropdownMenuContent({
   );
 }
 
+/** Groups related dropdown menu items for accessibility. */
 function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Group>) {
   return <DropdownMenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />;
 }
 
+/**
+ * A selectable action within the dropdown menu.
+ * Use variant="destructive" for dangerous actions like delete or logout.
+ */
 function DropdownMenuItem({
   className,
+  /** Adds left padding to align with items that have icons or indicators. */
   inset,
+  /** Use "destructive" for dangerous actions. */
   variant = 'default',
   ...props
 }: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
@@ -65,6 +76,7 @@ function DropdownMenuItem({
   );
 }
 
+/** A toggleable checkbox item within the dropdown menu. Shows a check indicator when active. */
 function DropdownMenuCheckboxItem({
   className,
   children,
@@ -91,10 +103,12 @@ function DropdownMenuCheckboxItem({
   );
 }
 
+/** Groups radio items for single-selection within the dropdown menu. */
 function DropdownMenuRadioGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
   return <DropdownMenuPrimitive.RadioGroup data-slot="dropdown-menu-radio-group" {...props} />;
 }
 
+/** A radio-selectable item within a DropdownMenuRadioGroup. Shows a dot indicator when selected. */
 function DropdownMenuRadioItem({
   className,
   children,
@@ -119,6 +133,7 @@ function DropdownMenuRadioItem({
   );
 }
 
+/** Non-interactive label within a dropdown menu, used for section headings. */
 function DropdownMenuLabel({
   className,
   inset,
@@ -136,6 +151,7 @@ function DropdownMenuLabel({
   );
 }
 
+/** Visual divider between groups of dropdown menu items. */
 function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
   return (
     <DropdownMenuPrimitive.Separator
@@ -146,6 +162,7 @@ function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typ
   );
 }
 
+/** Displays a keyboard shortcut hint aligned to the right side of a dropdown menu item. */
 function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<'span'>) {
   return (
     <span
@@ -156,10 +173,12 @@ function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<'spa
   );
 }
 
+/** Container for a submenu within the dropdown menu. */
 function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
   return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />;
 }
 
+/** Menu item that opens a nested submenu on hover or keyboard navigation. Shows a chevron indicator. */
 function DropdownMenuSubTrigger({
   className,
   inset,
@@ -184,6 +203,7 @@ function DropdownMenuSubTrigger({
   );
 }
 
+/** Popup content for a nested submenu. */
 function DropdownMenuSubContent({
   className,
   ...props

package/dist/starter/src/components/ui/Empty.stories.tsx

@@ -9,6 +9,7 @@ const meta: Meta<typeof Empty> = {
 export default meta;
 type Story = StoryObj<typeof Empty>;
 
+/** Shows a basic empty state with a title and description text. */
 export const Default: Story = {
   render: () => (
     <Empty>
@@ -20,6 +21,7 @@ export const Default: Story = {
   ),
 };
 
+/** Shows an empty state with a styled icon container above the title and description. */
 export const WithIcon: Story = {
   render: () => (
     <Empty>

package/dist/starter/src/components/ui/Empty.tsx

@@ -2,6 +2,11 @@ import { cva, type VariantProps } from 'class-variance-authority';
 
 import { cn } from '@/lib/utils';
 
+/**
+ * A placeholder component for empty states, such as no search results or empty inboxes.
+ * Compose with EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, and EmptyContent
+ * to build structured empty state layouts with icons and call-to-action areas.
+ */
 function Empty({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -15,6 +20,7 @@ function Empty({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** Container for the title, description, and optional media in an empty state. */
 function EmptyHeader({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -40,6 +46,10 @@ const emptyMediaVariants = cva(
   },
 );
 
+/**
+ * Container for an icon or illustration in the empty state.
+ * Use variant="icon" for a styled icon container with a muted background.
+ */
 function EmptyMedia({
   className,
   variant = 'default',
@@ -55,10 +65,12 @@ function EmptyMedia({
   );
 }
 
+/** Title text for the empty state message. */
 function EmptyTitle({ className, ...props }: React.ComponentProps<'div'>) {
   return <div data-slot="empty-title" className={cn('text-lg font-medium tracking-tight', className)} {...props} />;
 }
 
+/** Descriptive text explaining why the content is empty or what the user can do. */
 function EmptyDescription({ className, ...props }: React.ComponentProps<'p'>) {
   return (
     <div
@@ -72,6 +84,7 @@ function EmptyDescription({ className, ...props }: React.ComponentProps<'p'>) {
   );
 }
 
+/** Container for action buttons or additional content below the empty state message. */
 function EmptyContent({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div

package/dist/starter/src/components/ui/Field.stories.tsx

@@ -9,6 +9,7 @@ const meta: Meta<typeof Field> = {
 export default meta;
 type Story = StoryObj<typeof Field>;
 
+/** Shows a vertical form field with label, input, and helper description text. */
 export const Default: Story = {
   render: () => (
     <Field>
@@ -21,6 +22,7 @@ export const Default: Story = {
   ),
 };
 
+/** Shows a field in an invalid state with error styling and a validation error message. */
 export const WithError: Story = {
   render: () => (
     <Field data-invalid="true">
@@ -34,6 +36,7 @@ export const WithError: Story = {
   ),
 };
 
+/** Shows a field with horizontal orientation where the label and input are side by side. */
 export const Horizontal: Story = {
   render: () => (
     <Field orientation="horizontal">

package/dist/starter/src/components/ui/Field.tsx

@@ -7,6 +7,10 @@ import { cn } from '@/lib/utils';
 import { Label } from '@/components/ui/Label';
 import { Separator } from '@/components/ui/Separator';
 
+/**
+ * A semantic fieldset container for grouping related form fields.
+ * Use as a top-level wrapper around FieldGroup or multiple Field components.
+ */
 function FieldSet({ className, ...props }: React.ComponentProps<'fieldset'>) {
   return (
     <fieldset
@@ -21,6 +25,10 @@ function FieldSet({ className, ...props }: React.ComponentProps<'fieldset'>) {
   );
 }
 
+/**
+ * A legend element for a FieldSet, displayed as the group heading.
+ * Use variant="label" for a smaller label-sized heading.
+ */
 function FieldLegend({
   className,
   variant = 'legend',
@@ -36,6 +44,7 @@ function FieldLegend({
   );
 }
 
+/** Container for a group of Field components. Provides container query context for responsive layouts. */
 function FieldGroup({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -70,8 +79,14 @@ const fieldVariants = cva('group/field flex w-full gap-3 data-[invalid=true]:tex
   },
 });
 
+/**
+ * A form field wrapper that pairs a label with an input and optional description/error.
+ * Supports vertical, horizontal, and responsive orientations.
+ * Set data-invalid="true" to apply error styling.
+ */
 function Field({
   className,
+  /** Layout direction: "vertical" stacks label above input, "horizontal" places them side by side, "responsive" switches at the md breakpoint. */
   orientation = 'vertical',
   ...props
 }: React.ComponentProps<'div'> & VariantProps<typeof fieldVariants>) {
@@ -86,6 +101,7 @@ function Field({
   );
 }
 
+/** Container for the input element plus optional description and error within a Field. */
 function FieldContent({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -96,6 +112,7 @@ function FieldContent({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** Label for a form field. Supports wrapping checkbox/radio inputs for card-style selection. */
 function FieldLabel({ className, ...props }: React.ComponentProps<typeof Label>) {
   return (
     <Label
@@ -111,6 +128,7 @@ function FieldLabel({ className, ...props }: React.ComponentProps<typeof Label>)
   );
 }
 
+/** Non-interactive title text for a field, used when a label association is not needed. */
 function FieldTitle({ className, ...props }: React.ComponentProps<'div'>) {
   return (
     <div
@@ -124,6 +142,7 @@ function FieldTitle({ className, ...props }: React.ComponentProps<'div'>) {
   );
 }
 
+/** Helper text displayed below the input to provide additional guidance. */
 function FieldDescription({ className, ...props }: React.ComponentProps<'p'>) {
   return (
     <p
@@ -139,6 +158,7 @@ function FieldDescription({ className, ...props }: React.ComponentProps<'p'>) {
   );
 }
 
+/** A visual separator between fields within a FieldGroup. Optionally displays centered text. */
 function FieldSeparator({
   children,
   className,
@@ -166,9 +186,14 @@ function FieldSeparator({
   );
 }
 
+/**
+ * Displays validation error messages for a form field.
+ * Accepts either children or an errors array; deduplicates and renders as a list if multiple.
+ */
 function FieldError({
   className,
   children,
+  /** Array of error objects with message strings. Automatically deduplicated. */
   errors,
   ...props
 }: React.ComponentProps<'div'> & {

package/dist/starter/src/components/ui/Form.stories.tsx

@@ -39,6 +39,7 @@ function FormDemo() {
   );
 }
 
+/** Demonstrates a complete form field with label, input, description, and validation message wiring. */
 export const Default: Story = {
   render: () => <FormDemo />,
 };