@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/separator.tsx

@@ -4,84 +4,190 @@ import * as SeparatorPrimitive from "@radix-ui/react-separator";
 import { cn } from "@/lib/utils";
 
 /**
- * Separator component for visually dividing content sections
+ * Props for Separator component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace Radix inferred types
  *
- * A flexible separator component built on Radix UI primitives that creates
+ * Extends all props from Radix UI Separator Root primitive with additional styling options.
+ * Built on top of Radix UI Separator primitive for full accessibility compliance with WAI-ARIA separator role.
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type SeparatorDocsProps = {
+  /** Additional CSS class names to apply to the separator element */
+  className?: string;
+
+  /**
+   * The orientation of the separator
+   *
+   * - "horizontal": Creates a horizontal divider (full width, minimal height)
+   * - "vertical": Creates a vertical divider (minimal width, full height)
+   *
+   * @default "horizontal"
+   */
+  orientation?: "horizontal" | "vertical";
+
+  /**
+   * Whether the separator is purely decorative (visual only)
+   *
+   * When true, the separator is hidden from assistive technologies and serves only as a visual divider.
+   * When false, the separator is exposed to screen readers as a semantic boundary between content sections.
+   * Use false when the separator provides meaningful structure (e.g., between navigation sections).
+   *
+   * @default true
+   */
+  decorative?: boolean;
+
+  /**
+   * Polymorphic composition - render as a different element
+   *
+   * When true, renders the separator as its child element instead of a div.
+   * Useful for rendering as semantic HTML elements like <hr> while maintaining Radix UI behavior.
+   *
+   * @default false
+   */
+  asChild?: boolean;
+
+  /**
+   * ARIA label for semantic separators
+   *
+   * Provides an accessible name for the separator when decorative=false.
+   * Required for non-decorative separators to ensure proper screen reader announcement.
+   *
+   * @example "Navigation separator" or "Content section divider"
+   */
+  "aria-label"?: string;
+
+  /**
+   * ARIA labelledby for semantic separators
+   *
+   * References another element's ID that provides the accessible name for this separator.
+   * Alternative to aria-label for non-decorative separators.
+   */
+  "aria-labelledby"?: string;
+
+  /**
+   * Current value for interactive separators
+   *
+   * For focusable separators that can be moved (like split panes), this represents
+   * the current position value. Must be within the min/max range if specified.
+   */
+  "aria-valuenow"?: number;
+
+  /**
+   * Minimum value for interactive separators
+   *
+   * The minimum position value for moveable separators.
+   * Only relevant for focusable separators with aria-valuenow.
+   */
+  "aria-valuemin"?: number;
+
+  /**
+   * Maximum value for interactive separators
+   *
+   * The maximum position value for moveable separators.
+   * Only relevant for focusable separators with aria-valuenow.
+   */
+  "aria-valuemax"?: number;
+
+  /**
+   * Text description of current value
+   *
+   * Human-readable description of the current value for interactive separators.
+   * Example: "50% split" or "200 pixels from left"
+   */
+  "aria-valuetext"?: string;
+} & Omit<React.ComponentProps<"div">, "role">;
+
+/**
+ * Separator component for visually and semantically dividing content sections
+ *
+ * A flexible, accessible separator component built on Radix UI primitives that creates
  * visual or semantic divisions between content sections. Supports both horizontal
  * and vertical orientations with full accessibility features including decorative
- * and semantic separator modes for screen reader compatibility.
+ * and semantic separator modes for optimal screen reader compatibility.
+ *
+ * Built on Radix UI Separator primitive which automatically handles:
+ * - WAI-ARIA separator role compliance
+ * - Proper orientation data attributes
+ * - Screen reader visibility control via decorative prop
+ * - Keyboard navigation support for interactive separators
+ * - Semantic HTML structure with proper ARIA attributes
  *
  * @example
  * ```tsx
- * // Basic horizontal separator
- * <div>
- *   <p>Above content</p>
+ * // Basic horizontal separator - decorative divider
+ * <div className="space-y-4">
+ *   <p>Content above</p>
  *   <Separator />
- *   <p>Below content</p>
+ *   <p>Content below</p>
  * </div>
  * ```
  *
  * @example
  * ```tsx
- * // Vertical separator in toolbars
- * <div className="flex items-center">
+ * // Vertical separator in toolbar layouts
+ * <div className="flex items-center space-x-2">
  *   <button>Bold</button>
- *   <Separator orientation="vertical" className="mx-2 h-6" />
  *   <button>Italic</button>
+ *   <Separator orientation="vertical" className="h-4" />
+ *   <button>Underline</button>
+ *   <button>Strike</button>
  * </div>
  * ```
  *
  * @example
  * ```tsx
- * // Semantic separator for navigation
- * <nav className="flex items-center">
- *   <a href="/home">Home</a>
+ * // Semantic separator with screen reader support
+ * <nav className="flex items-center space-x-2">
+ *   <a href="/dashboard">Dashboard</a>
  *   <Separator
  *     orientation="vertical"
  *     decorative={false}
  *     aria-label="Navigation separator"
- *     className="mx-2 h-4"
+ *     className="h-4"
  *   />
- *   <a href="/about">About</a>
+ *   <a href="/settings">Settings</a>
  * </nav>
  * ```
  *
  * @example
  * ```tsx
- * // Custom styled separator
- * <Separator className="my-6 h-0.5 bg-gradient-to-r from-transparent via-border to-transparent" />
+ * // Custom styled separator with gradient
+ * <Separator className="my-8 h-px bg-gradient-to-r from-transparent via-border to-transparent" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Polymorphic separator using semantic HTML
+ * <article>
+ *   <section>First section content</section>
+ *   <Separator asChild decorative={false} aria-label="Section divider">
+ *     <hr className="my-6" />
+ *   </Separator>
+ *   <section>Second section content</section>
+ * </article>
  * ```
  *
+ * @accessibility
+ * - Implements WAI-ARIA separator role automatically
+ * - Supports both decorative (visual-only) and semantic modes
+ * - When decorative=false, separator is announced by screen readers
+ * - Proper ARIA labeling support via aria-label or aria-labelledby
+ * - Orientation communicated via data-orientation attribute
+ * - Supports interactive separators with ARIA value properties
+ * - Keyboard navigation ready for focusable separator implementations
+ *
+ * @see {@link Button} for related interactive elements
  * @see {@link https://ui.shadcn.com/docs/components/separator} for design patterns
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/separator} for Radix UI API
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/separator/} for ARIA separator pattern
  * @since 1.0.0
- * @see {@link https://www.radix-ui.com/primitives/docs/components/separator} for API reference
- */
-/**
- * Props for the Separator component
- */
-type SeparatorProps = React.ComponentProps<typeof SeparatorPrimitive.Root> & {
-  /** Additional CSS class names to apply to the separator */
-  className?: string;
-  /** The orientation of the separator. @default "horizontal" */
-  orientation?: "horizontal" | "vertical";
-  /** Whether the separator is purely decorative (hidden from screen readers). @default true */
-  decorative?: boolean;
-};
-
-/**
- * Separator component implementation
- *
- * @param className - Additional CSS class names to apply
- * @param orientation - The orientation of the separator ("horizontal" | "vertical")
- * @param decorative - Whether the separator is decorative (hidden from screen readers)
- * @param props - Additional props passed to the underlying Radix Separator primitive
  */
 function Separator({
   className,
   orientation = "horizontal",
   decorative = true,
   ...props
-}: SeparatorProps) {
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
   return (
     <SeparatorPrimitive.Root
       data-slot="separator"
@@ -98,4 +204,4 @@ function Separator({
 
 Separator.displayName = "Separator";
 
-export { Separator, type SeparatorProps };
+export { Separator };