@neynar/ui 0.2.1 → 0.3.1

package/src/components/ui/kbd.tsx

@@ -0,0 +1,175 @@
+import { cn } from "@/lib/utils"
+
+/**
+ * Props for Kbd component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace HTML kbd element inferred types
+ */
+type KbdDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Content to display inside the keyboard key (text, icons, or components) */
+  children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLElement>, "children" | "className">;
+
+/**
+ * Props for KbdGroup component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace HTML div element inferred types
+ */
+type KbdGroupDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Kbd components or other content to group together */
+  children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "className">;
+
+/**
+ * Kbd - Display keyboard input and shortcuts
+ *
+ * A semantic component for representing keyboard keys, shortcuts, and input in documentation,
+ * tutorials, and UI instructions. Uses the HTML kbd element with consistent styling for
+ * monospace text, subtle background, and appropriate sizing. Supports icons, text, and
+ * modifier keys like Cmd, Shift, Ctrl, and Alt.
+ *
+ * @example
+ * ```tsx
+ * // Display a single keyboard key
+ * <Kbd>K</Kbd>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Display keyboard shortcuts with modifiers
+ * <KbdGroup>
+ *   <Kbd>⌘</Kbd>
+ *   <Kbd>K</Kbd>
+ * </KbdGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Display keyboard shortcuts in help text
+ * <p>
+ *   Press <Kbd>Ctrl</Kbd> + <Kbd>S</Kbd> to save your work
+ * </p>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Complex keyboard shortcut with multiple modifiers
+ * <KbdGroup>
+ *   <Kbd>Ctrl</Kbd>
+ *   <Kbd>Shift</Kbd>
+ *   <Kbd>P</Kbd>
+ * </KbdGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Display keyboard shortcuts with icons
+ * <KbdGroup>
+ *   <Kbd>
+ *     <Command className="h-3 w-3" />
+ *   </Kbd>
+ *   <Kbd>K</Kbd>
+ * </KbdGroup>
+ * ```
+ *
+ * @accessibility
+ * - Uses semantic HTML kbd element for keyboard input representation
+ * - Screen readers announce content naturally as keyboard input
+ * - Non-interactive by default (pointer-events-none) to avoid confusion
+ * - Sufficient color contrast for readability (WCAG 2.1 AA compliant)
+ * - Respects user font size preferences with relative sizing
+ * - Works within tooltips with adjusted contrast for visibility
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd} MDN kbd Element Reference
+ * @see {@link https://ui.shadcn.com/docs/components/kbd} shadcn/ui Kbd Documentation
+ * @see {@link KbdGroup} Group multiple keyboard keys together
+ * @since 1.0.0
+ */
+function Kbd({ className, ...props }: React.ComponentProps<"kbd">) {
+  return (
+    <kbd
+      data-slot="kbd"
+      className={cn(
+        "bg-muted text-muted-foreground pointer-events-none inline-flex h-5 w-fit min-w-5 items-center justify-center gap-1 rounded-sm px-1 font-sans text-xs font-medium select-none",
+        "[&_svg:not([class*='size-'])]:size-3",
+        "[[data-slot=tooltip-content]_&]:bg-background/20 [[data-slot=tooltip-content]_&]:text-background dark:[[data-slot=tooltip-content]_&]:bg-background/10",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+/**
+ * KbdGroup - Group multiple keyboard keys together
+ *
+ * A container component for grouping multiple Kbd components to represent complex keyboard
+ * shortcuts or key combinations. Automatically handles spacing between individual keys and
+ * provides semantic grouping. Useful for displaying shortcuts like "Ctrl+Shift+P" or "Cmd+K".
+ *
+ * @example
+ * ```tsx
+ * // Basic keyboard shortcut
+ * <KbdGroup>
+ *   <Kbd>Ctrl</Kbd>
+ *   <Kbd>C</Kbd>
+ * </KbdGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple modifier keys
+ * <KbdGroup>
+ *   <Kbd>⌘</Kbd>
+ *   <Kbd>⇧</Kbd>
+ *   <Kbd>P</Kbd>
+ * </KbdGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom separators using text
+ * <KbdGroup>
+ *   <Kbd>Ctrl</Kbd>
+ *   <span className="text-muted-foreground">+</span>
+ *   <Kbd>Alt</Kbd>
+ *   <span className="text-muted-foreground">+</span>
+ *   <Kbd>Delete</Kbd>
+ * </KbdGroup>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // In a command palette or menu item
+ * <div className="flex items-center justify-between">
+ *   <span>Open command palette</span>
+ *   <KbdGroup>
+ *     <Kbd>⌘</Kbd>
+ *     <Kbd>K</Kbd>
+ *   </KbdGroup>
+ * </div>
+ * ```
+ *
+ * @accessibility
+ * - Groups related keyboard keys semantically
+ * - Screen readers announce grouped keys naturally
+ * - Maintains visual separation between keys for clarity
+ * - Non-interactive to prevent accidental activation
+ * - Respects user preferences for font sizing and spacing
+ *
+ * @see {@link Kbd} Individual keyboard key display
+ * @since 1.0.0
+ */
+function KbdGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <kbd
+      data-slot="kbd-group"
+      className={cn("inline-flex items-center gap-1", className)}
+      {...props}
+    />
+  )
+}
+
+export { Kbd, KbdGroup, type KbdDocsProps, type KbdGroupDocsProps }

package/src/components/ui/skeleton.tsx

@@ -149,7 +149,7 @@ function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       data-slot="skeleton"
-      className={cn("bg-accent animate-pulse rounded-md", className)}
+      className={cn("bg-card animate-pulse rounded-md", className)}
       {...props}
     />
   );

package/src/components/ui/spinner.tsx

@@ -0,0 +1,211 @@
+import * as React from "react";
+import { Loader2Icon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Props for Spinner component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred SVG types
+ */
+type SpinnerDocsProps = {
+  /** Additional CSS classes for custom size, color, or animation speed styling */
+  className?: string;
+  /** Color of the spinner icon (uses currentColor by default, inherits from parent text color) */
+  color?: string;
+  /** Size of the spinner icon in pixels @default 16 */
+  size?: number | string;
+  /** Stroke width of the spinner lines @default 2 */
+  strokeWidth?: number | string;
+  /** Accessible label for screen readers describing the loading state @default "Loading" */
+  "aria-label"?: string;
+  /** Role attribute for accessibility @default "status" */
+  role?: string;
+  /** Whether the spinner should be hidden from assistive technologies @default false */
+  "aria-hidden"?: boolean | "false" | "true";
+  /** Describes the element that is currently loading */
+  "aria-describedby"?: string;
+  /** Indicates that the region is being updated */
+  "aria-live"?: "off" | "polite" | "assertive";
+  /** Indicates that the content is currently busy loading @default false */
+  "aria-busy"?: boolean;
+  /** Style object for inline CSS styling */
+  style?: React.CSSProperties;
+  /** Data attributes for testing or identification */
+  [key: `data-${string}`]: string | undefined;
+} & Omit<
+  React.SVGProps<SVGSVGElement>,
+  "color" | "size" | "strokeWidth" | "children"
+>;
+
+/**
+ * Spinner - Loading indicator with animated rotation
+ *
+ * A circular loading spinner built on the Lucide React Loader2 icon with smooth rotation
+ * animation. Provides visual feedback to users during asynchronous operations such as
+ * data fetching, form submissions, or content loading. The spinner is highly customizable
+ * through CSS classes and supports all standard SVG props for size, color, and styling.
+ *
+ * @example
+ * ```tsx
+ * // Basic loading spinner with default size (16px)
+ * <Spinner />
+ *
+ * // Custom size using Tailwind size utilities
+ * <Spinner className="size-6" />
+ * <Spinner className="size-8" />
+ * <Spinner className="size-12" />
+ *
+ * // Custom color using text color classes
+ * <Spinner className="text-primary" />
+ * <Spinner className="text-destructive" />
+ * <Spinner className="text-muted-foreground" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // In loading buttons
+ * import { Button } from "./button";
+ *
+ * <Button disabled>
+ *   <Spinner className="mr-2 size-4" />
+ *   Loading...
+ * </Button>
+ *
+ * <Button variant="outline" disabled>
+ *   <Spinner className="mr-2 size-4" />
+ *   Processing
+ * </Button>
+ *
+ * // Icon-only loading button
+ * <Button size="icon" disabled aria-label="Loading">
+ *   <Spinner className="size-4" />
+ * </Button>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Full-page loading state
+ * <div className="flex min-h-screen items-center justify-center">
+ *   <div className="text-center space-y-4">
+ *     <Spinner className="size-12 mx-auto" />
+ *     <p className="text-muted-foreground">Loading your dashboard...</p>
+ *   </div>
+ * </div>
+ *
+ * // Card loading state
+ * <div className="border rounded-lg p-8 flex flex-col items-center gap-3">
+ *   <Spinner className="size-8" />
+ *   <p className="text-sm text-muted-foreground">Fetching data...</p>
+ * </div>
+ *
+ * // Inline loading with text
+ * <p className="flex items-center gap-2 text-sm">
+ *   <Spinner className="size-4" />
+ *   Syncing your data...
+ * </p>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom animation speed
+ * // Slow rotation
+ * <Spinner className="animate-[spin_2s_linear_infinite]" />
+ *
+ * // Fast rotation
+ * <Spinner className="animate-[spin_0.5s_linear_infinite]" />
+ *
+ * // Custom size and color combination
+ * <Spinner
+ *   className="size-6 text-blue-500"
+ *   strokeWidth={3}
+ * />
+ *
+ * // With background overlay
+ * <div className="relative">
+ *   <div className="absolute inset-0 bg-background/50 backdrop-blur-sm flex items-center justify-center rounded-lg">
+ *     <Spinner className="size-8" />
+ *   </div>
+ *   <div>Your content here</div>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Conditional rendering with loading state
+ * function DataDisplay() {
+ *   const [isLoading, setIsLoading] = React.useState(true);
+ *
+ *   return (
+ *     <div className="space-y-4">
+ *       {isLoading ? (
+ *         <div className="flex justify-center p-8">
+ *           <Spinner className="size-6" />
+ *         </div>
+ *       ) : (
+ *         <div>Loaded content here</div>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ *
+ * // With aria-live region for screen reader announcements
+ * <div aria-live="polite" aria-atomic="true">
+ *   {isLoading && (
+ *     <div className="flex items-center gap-2">
+ *       <Spinner className="size-4" />
+ *       <span>Loading content, please wait...</span>
+ *     </div>
+ *   )}
+ * </div>
+ * ```
+ *
+ * @accessibility
+ * - Includes role="status" by default to announce loading state to screen readers
+ * - Default aria-label="Loading" provides context for assistive technologies
+ * - Can be customized with custom aria-label for specific loading contexts
+ * - Spinner animation respects user's prefers-reduced-motion preferences via Tailwind
+ * - For purely decorative spinners in buttons with text labels, consider aria-hidden="true"
+ * - When used in loading overlays, ensure parent container has proper aria-live region
+ * - Icon inherits color from parent text color (currentColor) for consistent theming
+ * - Meets WCAG 2.1 AA standards when used with sufficient color contrast
+ * - Consider adding visually hidden text for additional context: <span className="sr-only">Loading...</span>
+ *
+ * @size
+ * The spinner size can be controlled through:
+ * - Tailwind size utilities: size-3 (12px), size-4 (16px), size-5 (20px), size-6 (24px), size-8 (32px), size-12 (48px)
+ * - Lucide size prop: <Spinner size={24} /> for pixel-based sizing
+ * - Custom width/height classes: w-10 h-10 for specific dimensions
+ * - Default size is 16px (size-4) when no size is specified
+ *
+ * @color
+ * The spinner color inherits from the parent text color by default:
+ * - text-primary for brand colors
+ * - text-destructive for error states
+ * - text-muted-foreground for subtle loading indicators
+ * - text-primary-foreground for use on colored backgrounds
+ * - Custom colors via arbitrary values: text-[#FF0000]
+ *
+ * @animation
+ * - Uses Tailwind's animate-spin utility (360° rotation, 1s linear infinite)
+ * - Respects prefers-reduced-motion media query automatically
+ * - Can be customized with arbitrary animation values for different speeds
+ * - Smooth 60fps rotation on modern browsers
+ *
+ * @see {@link https://lucide.dev/guide/packages/lucide-react} Lucide React documentation
+ * @see {@link https://lucide.dev/icons/loader} Loader2 icon details
+ * @see {@link https://lucide.dev/guide/advanced/accessibility} Lucide accessibility guide
+ * @see {@link Button} Button component for loading button patterns
+ * @since 1.0.0
+ */
+function Spinner({ className, ...props }: React.ComponentProps<"svg">) {
+  return (
+    <Loader2Icon
+      role="status"
+      aria-label="Loading"
+      className={cn("size-4 animate-spin", className)}
+      {...props}
+    />
+  );
+}
+
+export { Spinner, type SpinnerDocsProps };

package/src/components/ui/stack.tsx

@@ -475,7 +475,9 @@ const Stack = React.forwardRef<
     <div
       ref={ref}
       className={cn(
-        direction === "vertical" ? "flex flex-col" : "flex flex-row",
+        direction === "vertical"
+          ? "flex flex-col"
+          : "flex flex-row items-center",
         {
           "space-y-0": direction === "vertical" && spacing === 0,
           "space-y-1": direction === "vertical" && spacing === 1,

package/src/components/ui/stories/accordion.stories.tsx

@@ -19,7 +19,6 @@ const meta = {
       },
     },
   },
-  tags: ["autodocs"],
   argTypes: {
     type: {
       control: { type: "radio" },

package/src/components/ui/stories/alert-dialog.stories.tsx

@@ -32,7 +32,6 @@ const meta = {
       },
     },
   },
-  tags: ["autodocs"],
 } satisfies Meta<typeof AlertDialog>;
 
 export default meta;

package/src/components/ui/stories/alert.stories.tsx

@@ -15,7 +15,6 @@ const meta = {
       },
     },
   },
-  tags: ["autodocs"],
   argTypes: {
     variant: {
       control: { type: "select" },

package/src/components/ui/stories/aspect-ratio.stories.tsx

@@ -13,7 +13,6 @@ const meta = {
       },
     },
   },
-  tags: ["autodocs"],
   argTypes: {
     ratio: {
       control: { type: "number", min: 0.1, max: 5, step: 0.1 },

package/src/components/ui/stories/avatar.stories.tsx

@@ -14,7 +14,6 @@ const meta = {
       },
     },
   },
-  tags: ["autodocs"],
   argTypes: {
     className: {
       control: { type: "text" },

package/src/components/ui/stories/badge.stories.tsx

@@ -14,7 +14,6 @@ const meta = {
       },
     },
   },
-  tags: ["autodocs"],
   argTypes: {
     variant: {
       control: { type: "select" },

package/src/components/ui/stories/breadcrumb.stories.tsx

@@ -28,7 +28,6 @@ const meta = {
       },
     },
   },
-  tags: ["autodocs"],
   argTypes: {
     // No direct props on Breadcrumb component, but we can show composition options
     children: {