@neynar/ui 0.1.1 → 0.1.3

package/src/components/ui/popover.tsx

@@ -3,6 +3,125 @@ import * as PopoverPrimitive from "@radix-ui/react-popover";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Props for Popover root component (Documentation only - NOT used in component implementation)
+ * Controls the open/closed state and behavior of the popover system.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PopoverDocsProps = {
+  /** Whether the popover is open. Use for controlled state management. */
+  open?: boolean;
+  /** Callback fired when the open state changes. Use for controlled state management. */
+  onOpenChange?: (open: boolean) => void;
+  /** The initial open state for uncontrolled usage @default false */
+  defaultOpen?: boolean;
+  /** Whether the popover should be modal, preventing interaction with elements behind it @default false */
+  modal?: boolean;
+  /** Direction of text reading for proper positioning @default "ltr" */
+  dir?: "ltr" | "rtl";
+  /** The children components - typically PopoverTrigger and PopoverContent */
+  children?: React.ReactNode;
+};
+
+/**
+ * Props for PopoverTrigger component (Documentation only - NOT used in component implementation)
+ * The interactive element that opens/closes the popover when activated.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PopoverTriggerDocsProps = {
+  /**
+   * Changes the default rendered element to the one passed as a child, merging their props and behavior.
+   * Use this when you want to wrap a custom component instead of rendering a default button element.
+   * @default false
+   */
+  asChild?: boolean;
+  /** The content to display inside the trigger element */
+  children?: React.ReactNode;
+  /** Additional CSS classes to apply to the trigger */
+  className?: string;
+  /** Whether the trigger is disabled @default false */
+  disabled?: boolean;
+} & React.ButtonHTMLAttributes<HTMLButtonElement>;
+
+/**
+ * Props for PopoverContent component (Documentation only - NOT used in component implementation)
+ * The container that displays the popover content with positioning and styling.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PopoverContentDocsProps = {
+  /**
+   * The preferred side of the trigger to render the popover against
+   * @default "bottom"
+   */
+  side?: "top" | "right" | "bottom" | "left";
+  /**
+   * How to align the popover relative to the trigger along the cross axis
+   * @default "center"
+   */
+  align?: "start" | "center" | "end";
+  /**
+   * Distance in pixels from the trigger element
+   * @default 4
+   */
+  sideOffset?: number;
+  /**
+   * Offset in pixels along the alignment axis
+   * @default 0
+   */
+  alignOffset?: number;
+  /**
+   * Whether to automatically reposition to avoid collisions with viewport edges
+   * @default true
+   */
+  avoidCollisions?: boolean;
+  /**
+   * The boundary area to consider for collision detection. Can be an element, array of elements, or boundary descriptor.
+   * @default "clippingAncestors"
+   */
+  collisionBoundary?: Element | Element[] | null;
+  /**
+   * The padding between the boundary and the content during collision detection
+   * @default 0
+   */
+  collisionPadding?:
+    | number
+    | Partial<Record<"top" | "right" | "bottom" | "left", number>>;
+  /**
+   * Whether to stick to the boundary edges when repositioning due to collisions
+   * @default "partial"
+   */
+  sticky?: "partial" | "always";
+  /**
+   * Whether to hide the content when the trigger is fully occluded
+   * @default false
+   */
+  hideWhenDetached?: boolean;
+  /** The content to display inside the popover */
+  children?: React.ReactNode;
+  /** Additional CSS classes to apply to the content container */
+  className?: string;
+  /** Custom inline styles */
+  style?: React.CSSProperties;
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for PopoverAnchor component (Documentation only - NOT used in component implementation)
+ * Optional element to use as positioning reference instead of the trigger.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PopoverAnchorDocsProps = {
+  /**
+   * Changes the default rendered element to the one passed as a child, merging their props and behavior.
+   * Use this to wrap your own component that should serve as the positioning anchor.
+   * @default false
+   */
+  asChild?: boolean;
+  /** The content that will serve as the positioning reference */
+  children?: React.ReactNode;
+  /** Additional CSS classes to apply to the anchor */
+  className?: string;
+} & React.HTMLAttributes<HTMLElement>;
+
 /**
  * Popover displays rich content in a portal, triggered by a button
  *
@@ -86,14 +205,6 @@ import { cn } from "@/lib/utils";
  * @see {@link https://www.radix-ui.com/primitives/docs/components/popover} Radix Popover Primitive
  * @since 1.0.0
  */
-/**
- * Root popover component that manages open/closed state
- *
- * @param open - Controls the open state of the popover
- * @param onOpenChange - Event handler called when the open state changes
- * @param defaultOpen - The initial open state for uncontrolled usage
- * @param modal - Whether the popover should be modal (default: false)
- */
 function Popover({
   ...props
 }: React.ComponentProps<typeof PopoverPrimitive.Root>) {

package/src/components/ui/progress.tsx

@@ -4,67 +4,166 @@ import * as ProgressPrimitive from "@radix-ui/react-progress";
 import { cn } from "@/lib/utils";
 
 /**
- * Progress component displays completion progress of tasks and operations
+ * Props for Progress component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ProgressDocsProps = {
+  /** The progress value from 0 to 100. When undefined, shows an indeterminate state. */
+  value?: number | null;
+  /** The maximum progress value. @default 100 */
+  max?: number;
+  /**
+   * A function to get the accessible label text representing the current value in a human-readable format.
+   * If not provided, the value label will be read as the numeric value as a percentage of the max value.
+   * @param value Current progress value
+   * @param max Maximum progress value
+   * @returns Human-readable progress description
+   */
+  getValueLabel?: (value: number, max: number) => string;
+  /** Additional CSS classes for styling customization */
+  className?: string;
+  /**
+   * Change the default rendered element for the one passed as a child,
+   * merging their props and behavior. @default false
+   */
+  asChild?: boolean;
+  /** ARIA label for screen readers describing the progress element */
+  "aria-label"?: string;
+  /** ARIA text value providing human-readable description of progress */
+  "aria-valuetext"?: string;
+  /** ARIA description of the progress element */
+  "aria-describedby"?: string;
+  /** ARIA label referenced by element ID */
+  "aria-labelledby"?: string;
+  /** Unique identifier for the progress element */
+  id?: string;
+  /** Custom data attributes */
+  [key: `data-${string}`]: string | number | boolean | undefined;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "value" | "max">;
+
+/**
+ * Progress - Visual progress indicator for tasks and operations
  *
- * A visual progress indicator built on Radix UI primitives that shows the
- * completion state of tasks, file uploads, multi-step processes, and other
- * operations requiring user feedback about progress status.
+ * A customizable progress bar component built on Radix UI Progress primitive that displays
+ * the completion status of tasks, file uploads, multi-step processes, and other operations
+ * requiring user feedback. Features smooth animations, accessibility support, and flexible
+ * styling options.
  *
- * @example Basic usage
+ * @example Basic progress bar
  * ```tsx
  * <Progress value={60} />
  * ```
  *
- * @example With label and percentage
+ * @example With custom maximum value
+ * ```tsx
+ * <Progress value={30} max={50} />
+ * ```
+ *
+ * @example Indeterminate state (loading)
+ * ```tsx
+ * <Progress />
+ * ```
+ *
+ * @example With accessible label
+ * ```tsx
+ * <Progress
+ *   value={75}
+ *   aria-label="Installation progress"
+ *   getValueLabel={(value, max) => `${value} of ${max} files installed`}
+ * />
+ * ```
+ *
+ * @example File upload progress with label
+ * ```tsx
+ * <div className="space-y-2">
+ *   <div className="flex justify-between text-sm">
+ *     <span>Uploading image.jpg</span>
+ *     <span>{uploadProgress}%</span>
+ *   </div>
+ *   <Progress value={uploadProgress} />
+ * </div>
+ * ```
+ *
+ * @example Custom styling with different heights and colors
  * ```tsx
+ * <div className="space-y-4">
+ *   <Progress value={25} className="h-1" />
+ *   <Progress value={50} className="h-3" />
+ *   <Progress value={75} className="h-4 [&>div]:bg-green-500" />
+ *   <Progress value={100} className="h-6 [&>div]:bg-gradient-to-r [&>div]:from-blue-500 [&>div]:to-purple-500" />
+ * </div>
+ * ```
+ *
+ * @example Multi-step process indicator
+ * ```tsx
+ * const currentStep = 3;
+ * const totalSteps = 5;
+ * const stepProgress = (currentStep / totalSteps) * 100;
+ *
  * <div className="space-y-2">
  *   <div className="flex justify-between text-sm">
- *     <span>Loading data...</span>
- *     <span>{progress}%</span>
+ *     <span>Step {currentStep} of {totalSteps}</span>
+ *     <span>{Math.round(stepProgress)}%</span>
  *   </div>
- *   <Progress value={progress} />
+ *   <Progress
+ *     value={stepProgress}
+ *     getValueLabel={(value, max) => `Step ${currentStep} of ${totalSteps} complete`}
+ *   />
  * </div>
  * ```
  *
- * @example File upload progress
+ * @example Form validation progress
  * ```tsx
+ * const validFields = 4;
+ * const totalFields = 6;
+ * const validationProgress = (validFields / totalFields) * 100;
+ *
  * <div className="space-y-2">
- *   <Progress value={uploadProgress} />
  *   <p className="text-sm text-muted-foreground">
- *     {uploadProgress}% of 2.4 MB uploaded
+ *     Form completion: {validFields}/{totalFields} fields
  *   </p>
+ *   <Progress
+ *     value={validationProgress}
+ *     className="[&>div]:bg-emerald-500"
+ *     aria-label="Form completion progress"
+ *   />
  * </div>
  * ```
  *
- * @example Custom height and colors
+ * @example Reading progress indicator
  * ```tsx
+ * const scrollProgress = Math.min(100, (scrollY / (documentHeight - windowHeight)) * 100);
+ *
  * <Progress
- *   value={85}
- *   className="h-4 [&>div]:bg-green-500"
+ *   value={scrollProgress}
+ *   className="fixed top-0 left-0 right-0 z-50 h-1 rounded-none"
+ *   aria-label={`Reading progress: ${Math.round(scrollProgress)}%`}
  * />
  * ```
  *
- * @example Multi-step process
- * ```tsx
- * const stepProgress = (currentStep / totalSteps) * 100;
- * <Progress value={stepProgress} />
- * ```
- *
- * @param value - Progress value from 0 to 100. Undefined shows no progress.
- * @param className - Additional CSS classes for styling customization
- *
  * @accessibility
- * - Built on Radix UI Progress primitive with proper ARIA attributes
- * - Announces progress changes to screen readers
- * - Supports custom aria-label and aria-valuetext for enhanced descriptions
- * - Smooth visual transitions provide clear feedback
+ * - Built on Radix UI Progress primitive with full ARIA support
+ * - Automatically announces progress changes to screen readers via `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
+ * - Supports custom `aria-label` for descriptive labeling
+ * - Uses `getValueLabel` to provide human-readable progress descriptions
+ * - Includes `role="progressbar"` for proper semantic meaning
+ * - Supports `aria-valuetext` for custom progress descriptions
+ * - Visual progress changes are communicated through color, position, and optional text
+ * - Keyboard navigation is not required as this is a read-only indicator
+ * - Compatible with screen readers and other assistive technologies
+ * - Respects user's motion preferences for animations
  *
- * @see {@link https://ui.shadcn.com/docs/components/progress} for design patterns
+ * @see {@link https://www.radix-ui.com/docs/primitives/components/progress} Radix UI Progress Documentation
+ * @see {@link https://ui.shadcn.com/docs/components/progress} shadcn/ui Progress Component
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/progressbar_role} MDN progressbar role
  * @since 1.0.0
  */
 function Progress({
   className,
   value,
+  max = 100,
+  getValueLabel,
   ...props
 }: React.ComponentProps<typeof ProgressPrimitive.Root>) {
   return (
@@ -74,6 +173,9 @@ function Progress({
         "bg-primary/20 relative h-2 w-full overflow-hidden rounded-full",
         className,
       )}
+      value={value}
+      max={max}
+      getValueLabel={getValueLabel}
       {...props}
     >
       <ProgressPrimitive.Indicator