@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/chart.tsx

@@ -77,6 +77,227 @@ export type ChartConfig = {
   );
 };
 
+/**
+ * Props for ChartContainer component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ChartContainerDocsProps = {
+  /** Chart configuration defining series labels, colors, and icons */
+  config: ChartConfig;
+  /** Recharts component(s) to render within the responsive container */
+  children: React.ComponentProps<
+    typeof RechartsPrimitive.ResponsiveContainer
+  >["children"];
+  /** Unique identifier for the chart instance @default Generated unique ID */
+  id?: string;
+  /** Additional CSS classes for styling */
+  className?: string;
+  /** Inline styles for the container */
+  style?: React.CSSProperties;
+  /** ARIA label for accessibility */
+  "aria-label"?: string;
+  /** ARIA description for accessibility */
+  "aria-describedby"?: string;
+} & Omit<React.ComponentProps<"div">, "children">;
+
+/**
+ * Props for ChartTooltip component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Recharts inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ChartTooltipDocsProps = {
+  /** Custom content component for tooltip display */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  content?: React.ComponentType<any> | React.ReactElement;
+  /** Whether the tooltip is currently active/visible @default false */
+  active?: boolean;
+  /** Array of data objects to display in tooltip */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  payload?: any[];
+  /** Label value for current tooltip position (typically x-axis value) */
+  label?: string | number;
+  /** Function to format tooltip content */
+  formatter?: (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    value: any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    name: any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    props: any,
+  ) => [React.ReactNode, React.ReactNode] | React.ReactNode;
+  /** Function to format the tooltip label */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  labelFormatter?: (label: any, payload: any[]) => React.ReactNode;
+  /** Custom cursor component or cursor configuration @default true */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  cursor?: boolean | React.ComponentType<any> | React.ReactElement | object;
+  /** Custom position for tooltip placement */
+  position?: { x?: number; y?: number };
+  /** Distance from cursor/data point @default 10 */
+  offset?: number;
+  /** Whether tooltip shares data across all series @default Varies by chart type */
+  shared?: boolean;
+  /** Portal element to render tooltip outside chart container */
+  portal?: HTMLElement;
+  /** Wrapper styling for tooltip container */
+  wrapperStyle?: React.CSSProperties;
+  /** CSS class name for tooltip wrapper */
+  wrapperClassName?: string;
+  /** Animation duration in milliseconds @default 400 */
+  animationDuration?: number;
+  /** Animation easing function @default "ease" */
+  animationEasing?: string;
+  /** Whether tooltip is allowed to escape chart boundaries @default false */
+  allowEscapeViewBox?: { x?: boolean; y?: boolean };
+  /** Separator character between name and value @default " : " */
+  separator?: string;
+  /** Whether to use HTML for tooltip content @default false */
+  useTranslate3d?: boolean;
+  /** Custom coordinate for tooltip positioning */
+  coordinate?: { x?: number; y?: number };
+  /** Filter function for payload items */
+  filterNull?: boolean;
+  /** Custom item sorting function */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  itemSorter?: (item: any) => number;
+  /** Style for individual tooltip items */
+  itemStyle?: React.CSSProperties;
+  /** Style for tooltip labels */
+  labelStyle?: React.CSSProperties;
+  /** Style for tooltip content wrapper */
+  contentStyle?: React.CSSProperties;
+};
+
+/**
+ * Props for ChartTooltipContent component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ChartTooltipContentDocsProps = {
+  /** Whether to hide the label section of the tooltip @default false */
+  hideLabel?: boolean;
+  /** Whether to hide the color indicator for each data series @default false */
+  hideIndicator?: boolean;
+  /** Style of the color indicator shown for each series @default "dot" */
+  indicator?: "line" | "dot" | "dashed";
+  /** Key to use for extracting the name from payload data */
+  nameKey?: string;
+  /** Key to use for extracting the label from payload data */
+  labelKey?: string;
+  /** Whether the tooltip is currently active/visible */
+  active?: boolean;
+  /** Array of data objects to display in tooltip */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  payload?: any[];
+  /** Additional CSS classes for styling */
+  className?: string;
+  /** Label value for current tooltip position */
+  label?: string | number;
+  /** Function to format tooltip content */
+  formatter?: (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    value: any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    name: any,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    props: any,
+  ) => [React.ReactNode, React.ReactNode] | React.ReactNode;
+  /** Function to format the tooltip label */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  labelFormatter?: (label: any, payload: any[]) => React.ReactNode;
+  /** CSS class name for label styling */
+  labelClassName?: string;
+  /** Color override for indicators */
+  color?: string;
+} & React.ComponentProps<"div">;
+
+/**
+ * Props for ChartLegend component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Recharts inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ChartLegendDocsProps = {
+  /** Custom content component for legend display */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  content?: React.ComponentType<any> | React.ReactElement;
+  /** Array of legend items to display */
+  payload?: Array<{
+    value: string;
+    type?: string;
+    color?: string;
+    dataKey?: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    payload?: any;
+  }>;
+  /** Horizontal alignment of legend @default "center" */
+  align?: "left" | "center" | "right";
+  /** Vertical alignment of legend @default "bottom" */
+  verticalAlign?: "top" | "middle" | "bottom";
+  /** Height reserved for legend in pixels */
+  height?: number;
+  /** Width reserved for legend in pixels */
+  width?: number;
+  /** Wrapper styling for legend container */
+  wrapperStyle?: React.CSSProperties;
+  /** CSS class name for legend wrapper */
+  wrapperClassName?: string;
+  /** Layout direction for legend items @default "horizontal" */
+  layout?: "horizontal" | "vertical";
+  /** Size of legend icons in pixels @default 14 */
+  iconSize?: number;
+  /** Type of legend icons @default "rect" */
+  iconType?:
+    | "line"
+    | "rect"
+    | "circle"
+    | "cross"
+    | "diamond"
+    | "square"
+    | "star"
+    | "triangle"
+    | "wye";
+  /** Margin around legend container */
+  margin?: { top?: number; right?: number; bottom?: number; left?: number };
+  /** Click handler for legend items */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onClick?: (data: any, index: number, event: React.MouseEvent) => void;
+  /** Mouse enter handler for legend items */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onMouseEnter?: (data: any, index: number, event: React.MouseEvent) => void;
+  /** Mouse leave handler for legend items */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onMouseLeave?: (data: any, index: number, event: React.MouseEvent) => void;
+  /** Function to format legend content */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  formatter?: (value: any, entry: any, index: number) => React.ReactNode;
+};
+
+/**
+ * Props for ChartLegendContent component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type ChartLegendContentDocsProps = {
+  /** Whether to hide series icons from the chart configuration @default false */
+  hideIcon?: boolean;
+  /** Key to use for extracting the name from payload data */
+  nameKey?: string;
+  /** Array of legend items to display */
+  payload?: Array<{
+    value: string;
+    type?: string;
+    color?: string;
+    dataKey?: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    payload?: any;
+  }>;
+  /** Vertical alignment for automatic padding adjustment @default "bottom" */
+  verticalAlign?: "top" | "middle" | "bottom";
+  /** Additional CSS classes for styling */
+  className?: string;
+} & React.ComponentProps<"div">;
+
 type ChartContextProps = {
   config: ChartConfig;
 };
@@ -557,7 +778,7 @@ function ChartTooltipContent({
                     !hideIndicator && (
                       <div
                         className={cn(
-                          "shrink-0 rounded-[2px] border-(--color-border) bg-(--color-bg)",
+                          "shrink-0 rounded-[2px] border-border bg-background",
                           {
                             "h-2.5 w-2.5": indicator === "dot",
                             "w-1": indicator === "line",

package/src/components/ui/checkbox.tsx

@@ -4,6 +4,72 @@ import { CheckIcon } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 
+/**
+ * Props for Checkbox 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 CheckboxDocsProps = {
+  /** Additional CSS classes to apply to the checkbox */
+  className?: string;
+  /** 
+   * Change the default rendered element for the one passed as a child, 
+   * merging their props and behavior. Enables composition patterns.
+   * @default false 
+   */
+  asChild?: boolean;
+  /** 
+   * The controlled checked state of the checkbox. 
+   * Can be true (checked), false (unchecked), or "indeterminate" (partial selection).
+   * Use with onCheckedChange for controlled behavior. 
+   */
+  checked?: boolean | "indeterminate";
+  /** 
+   * The checked state of the checkbox when it is initially rendered. 
+   * Use when you do not need to control the checked state.
+   * Can be true, false, or "indeterminate" for initial state.
+   */
+  defaultChecked?: boolean | "indeterminate";
+  /** 
+   * Event handler called when the checked state of the checkbox changes.
+   * Receives the new checked state as a parameter.
+   */
+  onCheckedChange?: (checked: boolean | "indeterminate") => void;
+  /** 
+   * When true, prevents the user from interacting with the checkbox.
+   * The checkbox will be rendered with disabled styling and cannot receive focus.
+   */
+  disabled?: boolean;
+  /** 
+   * When true, indicates that the user must check the checkbox before form submission.
+   * This adds HTML5 form validation and appropriate ARIA attributes.
+   */
+  required?: boolean;
+  /** 
+   * The name of the checkbox field. Submitted with its owning form as part of form data.
+   * Essential for form handling and server-side processing.
+   */
+  name?: string;
+  /** 
+   * The value given as data when submitted with a name in a form.
+   * @default "on"
+   */
+  value?: string;
+  /** 
+   * Unique identifier for the checkbox. Should be used with Label htmlFor prop 
+   * for proper accessibility and click handling.
+   */
+  id?: string;
+  /** ARIA label for accessibility when no visible label is present */
+  "aria-label"?: string;
+  /** ID of an element that labels this checkbox for screen readers */
+  "aria-labelledby"?: string;
+  /** ID of an element that describes this checkbox for additional context */
+  "aria-describedby"?: string;
+  /** Indicates whether the checkbox has a validation error for screen readers */
+  "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling";
+} & React.HTMLAttributes<HTMLButtonElement>;
+
 /**
  * A versatile checkbox component for binary and multi-selection interfaces
  *
@@ -12,7 +78,11 @@ import { cn } from "@/lib/utils";
  * and comprehensive form integration. Features consistent styling with the design
  * system and proper keyboard navigation.
  *
- * @example Basic usage
+ * The component automatically renders a hidden input element when used within a form
+ * to ensure proper form submission and native validation support. Supports three states:
+ * checked (true), unchecked (false), and indeterminate for partial selections.
+ *
+ * @example Basic usage with Label
  * ```tsx
  * <div className="flex items-center space-x-2">
  *   <Checkbox id="terms" />
@@ -37,55 +107,123 @@ import { cn } from "@/lib/utils";
  * @example Indeterminate state for parent-child relationships
  * ```tsx
  * const [parentState, setParentState] = useState("indeterminate");
+ * const [childStates, setChildStates] = useState([true, false, true]);
  *
- * <Checkbox
- *   checked={parentState}
- *   onCheckedChange={(checked) => {
- *     setParentState(checked);
- *     // Update child checkboxes accordingly
- *   }}
- * />
+ * <div className="space-y-2">
+ *   <div className="flex items-center space-x-2">
+ *     <Checkbox
+ *       id="parent"
+ *       checked={parentState}
+ *       onCheckedChange={(checked) => {
+ *         setParentState(checked);
+ *         if (checked === true) {
+ *           setChildStates([true, true, true]);
+ *         } else if (checked === false) {
+ *           setChildStates([false, false, false]);
+ *         }
+ *       }}
+ *     />
+ *     <Label htmlFor="parent">Select all options</Label>
+ *   </div>
+ *   {childStates.map((childChecked, index) => (
+ *     <div key={index} className="flex items-center space-x-2 ml-6">
+ *       <Checkbox
+ *         id={`child-${index}`}
+ *         checked={childChecked}
+ *         onCheckedChange={(checked) => {
+ *           const newStates = [...childStates];
+ *           newStates[index] = checked;
+ *           setChildStates(newStates);
+ *           // Update parent based on child states
+ *           const checkedCount = newStates.filter(Boolean).length;
+ *           if (checkedCount === 0) setParentState(false);
+ *           else if (checkedCount === newStates.length) setParentState(true);
+ *           else setParentState("indeterminate");
+ *         }}
+ *       />
+ *       <Label htmlFor={`child-${index}`}>Option {index + 1}</Label>
+ *     </div>
+ *   ))}
+ * </div>
  * ```
  *
  * @example Form integration with multiple selections
  * ```tsx
  * const [preferences, setPreferences] = useState([]);
+ * const options = [
+ *   { id: "email", label: "Email notifications", value: "email" },
+ *   { id: "sms", label: "SMS notifications", value: "sms" },
+ *   { id: "push", label: "Push notifications", value: "push" }
+ * ];
  *
- * {options.map((option) => (
- *   <div key={option.id} className="flex items-center space-x-2">
- *     <Checkbox
- *       id={option.id}
- *       name="preferences"
- *       value={option.value}
- *       checked={preferences.includes(option.id)}
- *       onCheckedChange={(checked) => {
- *         setPreferences(prev =>
- *           checked
- *             ? [...prev, option.id]
- *             : prev.filter(id => id !== option.id)
- *         );
- *       }}
- *     />
- *     <Label htmlFor={option.id}>{option.label}</Label>
+ * <form onSubmit={(e) => {
+ *   e.preventDefault();
+ *   const formData = new FormData(e.currentTarget);
+ *   console.log(formData.getAll("preferences"));
+ * }}>
+ *   <fieldset className="space-y-3">
+ *     <legend className="text-sm font-medium">Notification Preferences</legend>
+ *     {options.map((option) => (
+ *       <div key={option.id} className="flex items-center space-x-2">
+ *         <Checkbox
+ *           id={option.id}
+ *           name="preferences"
+ *           value={option.value}
+ *           checked={preferences.includes(option.id)}
+ *           onCheckedChange={(checked) => {
+ *             setPreferences(prev =>
+ *               checked
+ *                 ? [...prev, option.id]
+ *                 : prev.filter(id => id !== option.id)
+ *             );
+ *           }}
+ *         />
+ *         <Label htmlFor={option.id}>{option.label}</Label>
+ *       </div>
+ *     ))}
+ *   </fieldset>
+ *   <button type="submit" className="mt-4">Save Preferences</button>
+ * </form>
+ * ```
+ *
+ * @example Disabled states
+ * ```tsx
+ * <div className="space-y-3">
+ *   <div className="flex items-center space-x-2">
+ *     <Checkbox id="disabled-unchecked" disabled />
+ *     <Label htmlFor="disabled-unchecked" className="text-muted-foreground">
+ *       Disabled unchecked
+ *     </Label>
+ *   </div>
+ *   <div className="flex items-center space-x-2">
+ *     <Checkbox id="disabled-checked" disabled defaultChecked />
+ *     <Label htmlFor="disabled-checked" className="text-muted-foreground">
+ *       Disabled checked
+ *     </Label>
  *   </div>
- * ))}
+ *   <div className="flex items-center space-x-2">
+ *     <Checkbox id="disabled-indeterminate" disabled checked="indeterminate" />
+ *     <Label htmlFor="disabled-indeterminate" className="text-muted-foreground">
+ *       Disabled indeterminate
+ *     </Label>
+ *   </div>
+ * </div>
  * ```
  *
- * @see {@link https://ui.shadcn.com/docs/components/checkbox} for design patterns
- * @since 1.0.0
+ * @accessibility
+ * - **Keyboard Navigation**: Space key toggles the checkbox state
+ * - **Screen Readers**: Properly announces state changes and supports required/invalid states
+ * - **Focus Management**: Receives focus and shows focus indicators
+ * - **Form Integration**: Automatically includes hidden input for form submission
+ * - **ARIA Support**: Uses proper ARIA states for checked/unchecked/indeterminate
+ * - **Labeling**: Should always be associated with a Label component using htmlFor and id
+ *
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/checkbox} Radix UI Checkbox primitive
+ * @see {@link https://ui.shadcn.com/docs/components/checkbox} shadcn/ui design patterns
  * @see {@link Label} for accessible labeling
- * @see {@link Switch} for boolean toggles
+ * @see {@link Switch} for boolean toggles with different semantics
  * @see {@link RadioGroup} for single selection scenarios
- *
- * @param className - Additional CSS classes to apply to the checkbox
- * @param checked - Controlled checked state (boolean | "indeterminate")
- * @param defaultChecked - Default checked state for uncontrolled usage
- * @param onCheckedChange - Callback when the checked state changes
- * @param disabled - Whether the checkbox is disabled
- * @param required - Whether the checkbox is required for form validation
- * @param name - Form field name for form submission
- * @param value - Form field value for form submission
- * @param id - Unique identifier, used with Label htmlFor attribute
+ * @since 1.0.0
  */
 function Checkbox({
   className,