@neynar/ui 0.1.1

package/src/components/ui/command.tsx

@@ -0,0 +1,518 @@
+import * as React from "react";
+import { Command as CommandPrimitive } from "cmdk";
+import { SearchIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+
+/**
+ * Command - A fast, composable command menu for search and navigation
+ *
+ * Built on the cmdk primitive, this component provides a powerful command palette
+ * interface with search, filtering, and keyboard navigation. Perfect for creating
+ * search interfaces, command palettes, and action menus with full accessibility support.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic command menu
+ * <Command>
+ *   <CommandInput placeholder="Type a command or search..." />
+ *   <CommandList>
+ *     <CommandEmpty>No results found.</CommandEmpty>
+ *     <CommandGroup heading="Suggestions">
+ *       <CommandItem>Calendar</CommandItem>
+ *       <CommandItem>Search Emoji</CommandItem>
+ *       <CommandItem>Calculator</CommandItem>
+ *     </CommandGroup>
+ *   </CommandList>
+ * </Command>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Command dialog with keyboard shortcut
+ * const [open, setOpen] = useState(false);
+ *
+ * useEffect(() => {
+ *   const down = (e: KeyboardEvent) => {
+ *     if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+ *       e.preventDefault();
+ *       setOpen((open) => !open);
+ *     }
+ *   };
+ *   document.addEventListener("keydown", down);
+ *   return () => document.removeEventListener("keydown", down);
+ * }, []);
+ *
+ * <CommandDialog open={open} onOpenChange={setOpen}>
+ *   <CommandInput placeholder="Type a command..." />
+ *   <CommandList>
+ *     <CommandGroup heading="Actions">
+ *       <CommandItem onSelect={() => console.log("New file")}>
+ *         New File
+ *         <CommandShortcut>⌘N</CommandShortcut>
+ *       </CommandItem>
+ *     </CommandGroup>
+ *   </CommandList>
+ * </CommandDialog>
+ * ```
+ *
+ * @accessibility
+ * - Full keyboard navigation with arrow keys and Home/End
+ * - Type-ahead search and filtering
+ * - Enter key to select items, Escape to close dialogs
+ * - Screen reader announcements for filtered results
+ * - ARIA roles following command palette pattern
+ * - Focus management and trapping in dialog mode
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/command} for design patterns
+ * @see {@link CommandDialog} - For modal command palette
+ * @see {@link CommandInput} - Search input component
+ * @see {@link CommandList} - Scrollable results container
+ * @since 1.0.0
+ */
+function Command({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive>) {
+  return (
+    <CommandPrimitive
+      data-slot="command"
+      className={cn(
+        "bg-popover text-popover-foreground flex h-full w-full flex-col overflow-hidden rounded-md",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CommandDialog - Modal dialog wrapper for command menu
+ *
+ * Presents the command menu in a modal dialog overlay, perfect for application-wide
+ * command palettes triggered by keyboard shortcuts like Cmd+K. Includes proper
+ * focus management and accessibility features.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Command palette dialog with keyboard shortcut
+ * const [open, setOpen] = useState(false);
+ *
+ * useEffect(() => {
+ *   const down = (e: KeyboardEvent) => {
+ *     if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+ *       e.preventDefault();
+ *       setOpen((open) => !open);
+ *     }
+ *   };
+ *   document.addEventListener("keydown", down);
+ *   return () => document.removeEventListener("keydown", down);
+ * }, []);
+ *
+ * <CommandDialog open={open} onOpenChange={setOpen}>
+ *   <CommandInput placeholder="Type a command..." />
+ *   <CommandList>
+ *     <CommandGroup heading="Actions">
+ *       <CommandItem>Create New File</CommandItem>
+ *       <CommandItem>Open Settings</CommandItem>
+ *     </CommandGroup>
+ *   </CommandList>
+ * </CommandDialog>
+ * ```
+ *
+ * @param title - Screen reader title for the dialog
+ * @param description - Screen reader description for the dialog
+ * @param showCloseButton - Whether to show the close button
+ *
+ * @accessibility
+ * - Focus trapped within dialog when open
+ * - Escape key closes the dialog
+ * - Screen reader announcements with title and description
+ * - Preserves all command menu keyboard navigation
+ *
+ * @since 1.0.0
+ */
+function CommandDialog({
+  title = "Command Palette",
+  description = "Search for a command to run...",
+  children,
+  className,
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof Dialog> & {
+  /**
+   * The title for screen readers
+   * @default "Command Palette"
+   */
+  title?: string;
+  /**
+   * The description for screen readers
+   * @default "Search for a command to run..."
+   */
+  description?: string;
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+  /**
+   * Whether to show the close button
+   * @default true
+   */
+  showCloseButton?: boolean;
+}) {
+  return (
+    <Dialog {...props}>
+      <DialogHeader className="sr-only">
+        <DialogTitle>{title}</DialogTitle>
+        <DialogDescription>{description}</DialogDescription>
+      </DialogHeader>
+      <DialogContent
+        className={cn("overflow-hidden p-0", className)}
+        showCloseButton={showCloseButton}
+      >
+        <Command className="[&_[cmdk-group-heading]]:text-muted-foreground **:data-[slot=command-input-wrapper]:h-12 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group]]:px-2 [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-input-wrapper]_svg]:h-5 [&_[cmdk-input-wrapper]_svg]:w-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:h-5 [&_[cmdk-item]_svg]:w-5">
+          {children}
+        </Command>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+/**
+ * CommandInput - Search input for command menu filtering
+ *
+ * Provides a search input with search icon for filtering command menu items.
+ * Automatically filters items as the user types and handles focus management.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <Command>
+ *   <CommandInput placeholder="Search commands..." />
+ *   <CommandList>...</CommandList>
+ * </Command>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled input with state
+ * <CommandInput
+ *   placeholder="Type a command or search..."
+ *   value={searchValue}
+ *   onValueChange={setSearchValue}
+ * />
+ * ```
+ *
+ * @accessibility
+ * - Auto-focuses when command menu opens
+ * - Live region announces result count to screen readers
+ * - Supports all standard input accessibility features
+ *
+ * @since 1.0.0
+ */
+function CommandInput({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Input>) {
+  return (
+    <div
+      data-slot="command-input-wrapper"
+      className="flex h-9 items-center gap-2 border-b px-3"
+    >
+      <SearchIcon className="size-4 shrink-0 opacity-50" />
+      <CommandPrimitive.Input
+        data-slot="command-input"
+        className={cn(
+          "placeholder:text-muted-foreground flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
+          className,
+        )}
+        {...props}
+      />
+    </div>
+  );
+}
+
+/**
+ * CommandList - Scrollable container for command items
+ *
+ * Contains and manages the list of command items with automatic scrolling
+ * and overflow handling. Manages keyboard navigation and selection state.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CommandList>
+ *   <CommandEmpty>No results found</CommandEmpty>
+ *   <CommandGroup heading="Actions">
+ *     <CommandItem>New File</CommandItem>
+ *     <CommandItem>Open File</CommandItem>
+ *   </CommandGroup>
+ * </CommandList>
+ * ```
+ *
+ * @accessibility
+ * - Scrollable with keyboard arrow navigation
+ * - Maintains focus within list boundaries
+ * - Supports Home/End key navigation
+ *
+ * @since 1.0.0
+ */
+function CommandList({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.List>) {
+  return (
+    <CommandPrimitive.List
+      data-slot="command-list"
+      className={cn(
+        "max-h-[300px] scroll-py-1 overflow-x-hidden overflow-y-auto",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CommandEmpty - Empty state message for command menu
+ *
+ * Displays when no command items match the current search query.
+ * Can contain custom content beyond simple text messages.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CommandList>
+ *   <CommandEmpty>No commands found.</CommandEmpty>
+ * </CommandList>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom empty state with icon and helpful text
+ * <CommandEmpty>
+ *   <div className="py-6 text-center">
+ *     <SearchIcon className="mx-auto h-10 w-10 text-muted-foreground/50" />
+ *     <h3 className="mt-2 text-sm font-medium">No results found</h3>
+ *     <p className="mt-1 text-sm text-muted-foreground">
+ *       Try adjusting your search terms.
+ *     </p>
+ *   </div>
+ * </CommandEmpty>
+ * ```
+ *
+ * @accessibility
+ * - Announced to screen readers when no results are found
+ * - Content is properly focusable if interactive
+ *
+ * @since 1.0.0
+ */
+function CommandEmpty({
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Empty>) {
+  return (
+    <CommandPrimitive.Empty
+      data-slot="command-empty"
+      className="py-6 text-center text-sm"
+      {...props}
+    />
+  );
+}
+
+/**
+ * CommandGroup - Groups related command items under a heading
+ *
+ * Organizes command items into labeled sections for better organization
+ * and navigation. Groups provide semantic structure for screen readers.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CommandGroup heading="Recent Files">
+ *   <CommandItem>document.pdf</CommandItem>
+ *   <CommandItem>presentation.pptx</CommandItem>
+ * </CommandGroup>
+ * <CommandGroup heading="Actions">
+ *   <CommandItem>New File</CommandItem>
+ *   <CommandItem>Open File</CommandItem>
+ * </CommandGroup>
+ * ```
+ *
+ * @param heading - The group heading text displayed above items
+ *
+ * @accessibility
+ * - Group headings are announced to screen readers
+ * - Provides semantic grouping for better navigation
+ * - Maintains keyboard navigation flow between groups
+ *
+ * @since 1.0.0
+ */
+function CommandGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Group>) {
+  return (
+    <CommandPrimitive.Group
+      data-slot="command-group"
+      className={cn(
+        "text-foreground [&_[cmdk-group-heading]]:text-muted-foreground overflow-hidden p-1 [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CommandSeparator - Visual separator between command groups
+ *
+ * Provides visual separation between different sections of commands.
+ * Purely decorative element that improves visual organization.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CommandGroup heading="Recent">...</CommandGroup>
+ * <CommandSeparator />
+ * <CommandGroup heading="Actions">...</CommandGroup>
+ * ```
+ *
+ * @accessibility
+ * - Decorative element, properly hidden from screen readers
+ * - Does not interfere with keyboard navigation
+ *
+ * @since 1.0.0
+ */
+function CommandSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Separator>) {
+  return (
+    <CommandPrimitive.Separator
+      data-slot="command-separator"
+      className={cn("bg-border -mx-1 h-px", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CommandItem - Individual selectable command item
+ *
+ * Represents a single command or action that can be selected via
+ * keyboard or mouse interaction. Supports icons, text, and shortcuts.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic command item
+ * <CommandItem onSelect={() => console.log("File opened")}>
+ *   Open File
+ * </CommandItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Command item with icon and shortcut
+ * <CommandItem value="new-document" onSelect={handleCreateDocument}>
+ *   <FileIcon className="mr-2 h-4 w-4" />
+ *   New Document
+ *   <CommandShortcut>⌘N</CommandShortcut>
+ * </CommandItem>
+ * ```
+ *
+ * @param value - Unique identifier for the item (used for filtering)
+ * @param onSelect - Callback when item is selected
+ * @param disabled - Whether the item is disabled
+ *
+ * @accessibility
+ * - Keyboard selectable with Enter key and arrow navigation
+ * - Visual highlight on focus and hover states
+ * - Supports disabled state with proper ARIA attributes
+ * - Screen reader announces item content and state
+ *
+ * @since 1.0.0
+ */
+function CommandItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandPrimitive.Item>) {
+  return (
+    <CommandPrimitive.Item
+      data-slot="command-item"
+      className={cn(
+        "data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CommandShortcut - Displays keyboard shortcut for command items
+ *
+ * Shows the keyboard shortcut associated with a command item,
+ * typically displayed on the right side. Supports platform-specific shortcuts.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CommandItem>
+ *   Save File
+ *   <CommandShortcut>⌘S</CommandShortcut>
+ * </CommandItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multi-key shortcuts
+ * <CommandItem>
+ *   Redo
+ *   <CommandShortcut>⇧⌘Z</CommandShortcut>
+ * </CommandItem>
+ * ```
+ *
+ * @accessibility
+ * - Semantically associated with its command item
+ * - Announced to screen readers as part of item description
+ * - Uses proper keyboard shortcut formatting
+ *
+ * @since 1.0.0
+ */
+function CommandShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="command-shortcut"
+      className={cn(
+        "text-muted-foreground ml-auto text-xs tracking-widest",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Command,
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
+  CommandSeparator,
+};

package/src/components/ui/container.tsx

@@ -0,0 +1,114 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * Props for the Container component
+ *
+ * @public
+ */
+export type ContainerProps = React.HTMLAttributes<HTMLDivElement> & {
+  /**
+   * The maximum width size of the container
+   *
+   * - `sm`: max-w-3xl (48rem) - Optimal for reading content, articles, and blog posts
+   * - `md`: max-w-5xl (64rem) - Suitable for forms, documentation, and medium-width layouts
+   * - `lg`: max-w-7xl (80rem) - Default size, ideal for main application content and dashboards
+   * - `xl`: max-w-none - No max-width constraint but maintains responsive padding
+   * - `full`: max-w-full - Full width container for edge-to-edge designs
+   *
+   * @default "lg"
+   */
+  size?: "sm" | "md" | "lg" | "xl" | "full";
+};
+
+/**
+ * A responsive content wrapper component that provides consistent max-width constraints and horizontal padding
+ *
+ * Container is inspired by layout patterns from shadcn/ui and Tailwind UI, offering a flexible foundation
+ * for page layouts. It automatically centers content horizontally and applies responsive padding that
+ * adapts gracefully across different screen sizes (px-4 on mobile, px-6 on small screens, px-8 on large screens).
+ *
+ * The component supports five size variants optimized for different content types:
+ * - Small containers for optimal reading experiences
+ * - Medium containers for forms and documentation
+ * - Large containers for application dashboards
+ * - Extra-large and full-width for specialized layouts
+ *
+ * @example Basic usage with default large size
+ * ```tsx
+ * <Container>
+ *   <h1>Dashboard Title</h1>
+ *   <p>Main application content with optimal width constraints</p>
+ * </Container>
+ * ```
+ *
+ * @example Reading-optimized container for articles
+ * ```tsx
+ * <Container size="sm">
+ *   <article>
+ *     <h1>Blog Post Title</h1>
+ *     <p>Long-form content with line lengths optimized for readability</p>
+ *   </article>
+ * </Container>
+ * ```
+ *
+ * @example Full-width layout for complex interfaces
+ * ```tsx
+ * <Container size="full">
+ *   <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+ *     <DashboardWidget />
+ *     <DashboardWidget />
+ *     <DashboardWidget />
+ *   </div>
+ * </Container>
+ * ```
+ *
+ * @example Composing with other layout components
+ * ```tsx
+ * <Container size="lg" className="py-8">
+ *   <Stack spacing="lg">
+ *     <Heading size="xl">Section Title</Heading>
+ *     <Text>Section description</Text>
+ *     <Card>Content card</Card>
+ *   </Stack>
+ * </Container>
+ * ```
+ *
+ * @accessibility
+ * - Uses semantic HTML `div` element that works well with screen readers
+ * - Maintains proper focus management and keyboard navigation flow
+ * - Responsive design ensures content remains accessible across all device sizes
+ * - Text content automatically reflows for optimal readability
+ * - Compatible with high contrast themes and browser zoom levels up to 200%
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/sidebar} Sidebar component for app layouts
+ * @see {@link https://ui.shadcn.com/blocks} shadcn/ui blocks for complete layout examples
+ *
+ * @public
+ * @since 1.0.0
+ */
+const Container = React.forwardRef<HTMLDivElement, ContainerProps>(
+  ({ className, size = "lg", ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "mx-auto w-full px-4 sm:px-6 lg:px-8",
+          {
+            "max-w-3xl": size === "sm",
+            "max-w-5xl": size === "md",
+            "max-w-7xl": size === "lg",
+            "max-w-none": size === "xl",
+            "max-w-full": size === "full",
+          },
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+Container.displayName = "Container";
+
+export { Container };